(Last updated: 03/21/2019 |Personal Opinion)
“Writing is nature’s way of letting you know how sloppy your thinking is.” -Dick Guindon
A few things related to software engineering practices at various places I worked bug me and experiences from almost half dozen of my previous jobs make me believe writing things down is an effective approach to tackle all these issues.
- Unpredictability. Show stopper functional gaps identified late in the release cycle; Passive quality control focusing solely on defects at the end of a release, while much of which are preventable in the early design and coding phase. Frequent fires.
- Lack of visibility. Hard to find out what each developer is working on. Have to rely on people managers to manage dev processes; Same wheels reinvented multiple times at different buildings.
- Accumulated technical and architectural debt. Different teams building things very differently, both approach-wise and quality-wise.
Writing Things Down
By writing things down, things become sharable, searchable, reviewable and trackable. An RFC like process injects collective thinking in our planning which provide visibility, reduces unpredictability and alleviate the accumulation of technical and architectural debt.
The case for written documents
Amazon CEO Jeff Bezos takes a peculiarly old school way of managing — writing it down. “In senior executive Amazon meetings, before any conversation or discussion begins, everyone sits for 30 minutes in total silence, carefully reading six-page printed memos. Reading together in the meeting guarantees everyone’s undivided attention to the issues at hand, but the real magic happens before the meeting ever starts. It happens when the author is writing the memo. In having to write it all down, authors are forced to think out tough questions and formulate clear, persuasive replies, reasoning through the structure and logic in the process. CEO of Intel, Andy Grove, echo Bezos’s view on writing: ‘[written reports are vital because] the author is forced to be more precise than he might be verbally [or mentally].’ ”
How do you encourage clear thinking out of the mediocre developers? Force them to write it down. How do you encourage innovative thinking out of top-notch developers? Force them to write it down. How do you drill down to the algorithm level of a critical piece of software to make sure it’s done right? Examine the design options considered in the technical design document. How do you intervene on an urgent but slow moving piece of software? Examine the task breakdown and development estimates in the technical design doc and bid the tasks out to other developers who can get the job done faster…
As you can see by now, written documents serve as a medium for direct manipulation of the otherwise elusive, intangible and opaque software development process.
Software development documents
Requirement doc, design doc and test plan are the communication, collaboration, tracking and contractual documents among stake holders from product management, R&D and testing. Predefined templates guide the thinking process of their authors. Contents of each doc can be group reviewed and improved upon for the merits there in. Documented ideas and design decisions serve as lasting institutional knowledge. The form of the documents doesn’t matter: Jira story, Word documents, plain text…What matters are the contents in the documents and the thoughts that went into producing those contents.
Consummate all documents is the software, in various maturity levels from prototype to release candidates. All stake holders should start playing with the software as soon as possible.
Functional Requirement Documents
Product manager writes the functional requirement documents. It contains at least below information:
- List of user scenarios
- List of functional requirements for each feature
- Performance requirement
Technical Design Documents
The two must-have pieces of a technical design document are design options and development estimates.
Design options
A mandate of at least three design options for each feature force the developer to search wide and deep for the optimal solutions to the problem at hand.
Development estimates
Development estimates force developers to break down the work into manageable pieces and offer their reasonable estimates. The estimates are essential to subsequent planning and control of the software development process.
Since the task break down and estimates are group reviewed and audited, slacking developers would think twice before inflating a two-hour task to three weeks.
Test Plans
The test cases in the test plan should cover the features in functional requirement document (black box testing), as well as the particular design decision the developer choose to implement (white box testing).
Collaborate with workflows, rather than meetings
How do we reduce meetings without hurting collaborations? Use workflows and collaboration tools! Save face to face meeting only to the outstanding issues that failed to be resolved with workflows.
Lifecycle of software development documents
Software development documents are living artifacts reflecting thoughts of the people and milestones of the process that produced them.
Workflow around documents
I found the email based PDF review process used by documentation team to be extremely efficient:
- Doc author sends emails to stake holders with a link to the draft doc.
- Each reviewers annotate and publish their comments to the review team.
- Doc author incorporate or reject each comments.
- The team meet to resolve the remaining concerns, only when necessary.
With the clear thinking instilled into the draft document and the collaboration incurred during the review workflow, the face to face meeting is rarely needed.
Workflows around software: Demo, anti-demo, Beta-labs
The demo done by development tends to focus on the fancy stuff, glossing over or ignoring what’s not working and the functional gaps between software as is and the functional requirements. To gain the most insights into the readiness of our software, the demo should NOT be done by the people who develop the software.
Product manager demo the software at early stages, by carrying out the use cases defined in the functional requirement documentation. This mandate has several advantages:
- Functional gaps are identified early by the people who defines the requirements.
- Usability issues are identified early.
- Product managers have the incentive to try the software early.
Developers and AX/UX designers are encouraged to do anti-demo: what’s NOT working, what’s users’ pain points using the software.
End users beta test the software at later stages. In lieu of real end users, folks from Education and Technical Support organizations are the best proxy for end users. Beta test should not be scripted step by step guide as now in our Beta lab sessions. Rather, follow below simple steps:
- Pair each user with an observer/helper: a developer, UX designer or product manager who either designed, developed or demoed the software in earlier stages.
- Just throw the use cases defined in functional design documents to the user and see what it takes for them to get the job done.
- The quirks and kinks along the way are the gaps in the requirement, design or implementation of the software. Observers take note and draw action plan to address the gaps.
It’s all about quality
The painstaking exercises of drafting, reviewing and updating of documents are preemptive measures to prevent bugs from creeping into the final product. Passively waiting bugs to be found by product testing at later stage of release cycle is stressful, unpredictable and uncontrollable.
To speed up, we must slow down
In short, the practice of writing things down calls for a cultural change with below mandates:
- Think more, (throw-away) coding less
- Write more, talk less
- Draw more, write less
- Collaborate more, meet less
The adoption of documents and workflows driven software development will be painful initially. People will inevitably complain about the extra time and efforts they have to put in on top of their daily work. But as less bugs, rewrites and delays happen because of the thoughts and planning efforts that went into the technical design, people will start to appreciate the preventive nature of the documents writing exercises. Only when these practices become habitual among team members, when surprises, fires and emergencies become a rare thing, we can finally achieve the peace of mind in our development work.
By the way, I didn’t invent any of these. It’s what I experienced and observed how professional software companies are run. The best learning experiences I had was reading Guru-of-the-team’s design doc and have a bunch of Gurus review the design doc of my own. Alas, how I miss those times!
References
- Python becomes the most popular language for a reason. All new features are carefully thought out, debated and documented in Python Enhancement Proposals(PEP). See for example all the thoughts that went into the module that parse command line options.
- Design docs at Google and discussions around it on Hacker news, with Chromium and Kubernetes as poster child.