Documentation-First Development
The act of writing end-user documentation before software development offers a host of surprising benefits.
What if you could combine two development activities that you know you should be doing into one, thus cutting in half the time you spend on stuff you'd rather avoid?
I'm referring to the following activities:
- Design
- Documentation
As programmers, we'd rather jump right into writing code, but skipping the design phase is the very definition of a false economy:
[A] false economy is an action that does save money at the beginning but which, over a longer period of time, results in more money being spent or wasted than being saved.
And while users never read documentation, it is nice to be able to refer them to it when they inevitably ask questions about how a feature is supposed to work.
So, how do we combine design and documentation into a single activity? We do it with Design-First Documentation (DFD).
Design-First Documentation
The concept is straightforward.
Before you write any code, you create the documentation that explains to the user how the system works. The user approves the documentation. You use the documentation as a specification to build the system.
Here's an example of how this works in practice:
- User requests a feature, such as a new report
- You write detailed documentation for the report:
• How to navigate to the location where the user will run the report
• What filters the user can apply when running the report
• A description of the fields that appear on the report
• A description of any group headers or footers - You provide the first draft of the documentation to the user
- The user provides feedback:
• What filters are needed that are not provided?
• Where are the directions confusing?
• Is there any required data missing from the report? - You revise the documentation based on the user feedback
- Repeat steps 4 and 5 until the user approves the documentation
- Build the feature (the report and associated filter form) based on the documentation
Advantages of DFD
Designing Before Coding Reduces Technical Debt
To start, you avoid all the dangers inherent in skipping the design phase as I wrote about in the following article from my sources of technical debt series:
Mike Wolfe
Misunderstood Requirements Get Caught Early
By involving the end user from the beginning, you also ensure that any misunderstood requirements get captured before writing code (when it's cheap and easy to fix) rather than after writing the code (when it is much more expensive):
Mike Wolfe
A Reference for Both Developer and End User
By creating documentation, you also have a handy reference for both you (as the developer) and your client (as the end user). To get the most value out of this aspect of DFD, it's important to include the why behind the design decisions you made, especially if they are exceptions to typical best practices.
Better Documentation
Most end user documentation for custom software–if it's written at all–is done after the project is complete. This means that any important design decisions have likely been forgotten about. It means that the person writing the documentation is doing it only to check a box. All the important context regarding how or why a feature works the way it does is likely missing from the documentation writer's mind.
Awkward User Experiences are Revealed
If you are having difficulty explaining how a planned feature works in your end-user documentation, then you probably need to rethink the design. "Explain it to me like I'm five," is a good frame of reference when writing your documentation. If that's too hard to do, then simplify the feature.
Sunk Cost Fallacy Avoided
The sunk cost fallacy might be responsible for more bad software than any other form of behavioral psychology:
The Sunk Cost Fallacy describes our tendency to follow through on an endeavor if we have already invested time, effort, or money into it, whether or not the current costs outweigh the benefits.
It's really hard to throw away code that we've spent hours writing. It can also be really hard to justify that to a client if you bill by the hour. Better to avoid writing the bad code in the first place. DFD helps you do that.
Disadvantages of DFD
Extra Time Up Front
The obvious one is the additional up-front time commitment. As I mentioned above, though, this is often a false economy. Time spent doing design will be time saved during implementation.
Waiting on the Client
This will vary by client. Some clients are very responsive to requests for feedback, but others will not be. A client that is slow to respond can grind your development to a halt. It's important to set timelines early in the process so that there are clear expectations for all involved parties.
The Iceberg Secret
Joel Spolsky defines the Iceberg Secret thusly:
You know how an iceberg is 90% underwater? Well, most software is like that too — there’s a pretty user interface that takes about 10% of the work, and then 90% of the programming work is under the covers.
...
That’s not the secret. The secret is that People Who Aren’t Programmers Do Not Understand This.
One of the risks you run with DFD is that users will see the documentation and assume the feature is nearly done. After all, that's how most software documentation is created: haphazardly after the system is complete. This risk will be exacerbated if you include screenshots in your pre-code documentation.
Users Don't Read Documentation
But maybe they will read good documentation?
Nice thought, but no. Users still won't read the documentation. But, having documentation means that answering questions about the system is a simple matter of referring the user to the documentation. RTFM, as the kids no longer say.
Acknowledgements
- Article excerpt generated with the help of ChatGPT
- Cover image created with Microsoft Designer
