The Art of Writing Good Documentation
Documentation is dead. It’s a big waste of time. It’s stale the moment it’s done. Nobody has the time to write it. Does anyone even read it?
All are good excuses for writing little to no documentation for your software projects. But that’s precisely what they are: excuses.
Because if good documentation “is a love letter you write to your future self” (Damian Conway), then no documentation is a trap you set for your future self.
Indeed, the art of creating, curating, and preserving quality project, product, and process documentation is facing a crisis in the age of “agile.” After all, are we not supposed to value “working software over comprehensive documentation?” So, then why bother writing any documentation at all?
I’ve yet to meet anyone who doesn’t appreciate good documentation and would like more of it, be it project, product, process, technical, or user documentation. The real issue is that nobody, and I mean NOBODY, likes writing them.
I get it. Documentation is hard. There is never enough of it. There is never enough time to write it. There are never enough resources to maintain it. The result is a self-perpetuating cycle of no or low documentation.
The only way to exit this vicious cycle is to create good documentation that captures the right things at the right time and in the right amount of detail. Honestly, any documentation is better than no documentation at all. Because writing good documentation, no matter how lean and mean, can go a long way in:
- Increasing productivity
- Cutting down on wasteful meetings
- Fostering understanding
- Facilitating quick onboarding and training
- Future-proofing changes in an organization
Good documentation is critical for business success
Documentation is the written and preserved history of a project, product, or process. The documentation tells us what we did, how we did it, and why we did it that way. This documentation can be in the form of requirements documents, user manuals, technical documentation, or even simple project planning documentation.
Documentation helps us:
1. Remember what we did. As our projects, products, and processes evolve, it’s easy to forget the details of how we got to where we are today. By documenting these things, we have a written record to which we can refer.
2. Communicate with others. Documenting our work forces us to articulate our thoughts in a way that others can easily understand. This is important when we need to share our work with others, whether team members, stakeholders, or customers.
3. Improve our work. By documenting our work, we can step back and take a bird’s eye view of what we’ve done. This can help us identify areas for improvement and make changes accordingly.
Despite these good reasons for documentation, it remains one of the most neglected aspects of software development. And that’s a shame because documentation is essential for the success of any project, product, or process.
So, how can we change this? How can we make documentation a priority in our organizations?
By making it a part of our culture.
Documentation should be an essential deliverable, just like code or a working prototype.
So, how should we get started?
Start small
Don’t boil the ocean. Start with a discrete slice of a project, product, or process to kick off the effort. Then, build as you go along. Don’t get overwhelmed by the size and scope of the task.
And most importantly, get started today. Don’t wait for the perfect moment or the perfect solution. There is no such thing. Documentation is never done. It’s always a work in progress. The goal is to make it better, not perfect.
Document the details that matter
For any given software or system change, this might include any or all of the following:
- The context for the problem you’re solving
- Overview of the change you’re making
- Decisions made
- Consequences of actions
- Parts of the system with lots of history
- Things that will hurt in the future if forgotten
Document the right things at the right time
Avoid documentation waste. Stay agile. Focus the bulk of your documentation efforts on documenting actually implemented features, necessary changes, and pertinent development details.
Minimize the time and effort spent on “detailed” plans, requirements, specifications, planned features, and architecture that can swiftly go stale. This does not mean that these kinds of documents are not needed. They are. You just have to be mindful of the depth of details you decide to capture in these kinds of documentation.
As a rule of thumb, documentation should be just detailed enough to help you and others do your jobs today without being so comprehensive that it bogs you down or quickly becomes unmaintainable and thus, unusable.
Choose the right documentation tools
Some documentation will have longer life spans than others. Choose your documentation tools and formats wisely. Not all documentation is created equal. And not all documentation needs to live forever. Some documents are meant to be read by humans, while others are for machines. Some documents need to be updated frequently, while others can be static.
Depending on the audience and purpose of your documentation, you might choose different tools and formats.
For example, documentation for developers might be stored in code repositories, and documentation for end users might be published as online help files or pdfs.
Crowdsource the documentation effort
Creating and maintaining documentation should be a shared activity, not the sole responsibility of an individual team member like the Project Manager or the Business Analyst. So, set up your documentation in a way that fosters collaboration.
For example, invite a broad selection of business and technical authors to contribute to the effort. Not only will this help to ensure that the documentation is comprehensive and accurate, but it will also help to build buy-in and ownership for the documentation itself.
Make work-in-progress documentation available for peer review and feedback
Don’t wait to reach perfection! Get the documentation in front of people who can provide meaningful additions, edits, and feedback. Don’t let your documentation languish in some corner of your wiki. Share them with others on your team, other departments, and external stakeholders.
By making documentation a collaborative effort, you can ensure that it is accurate and up-to-date.
Assign documentation owners and stewards
Documentation should be owned and stewarded by someone on the team. This doesn’t mean that everyone else is off the hook when it comes to documentation. But it does mean that designated people own the responsibility for documentation quality and accuracy. These documentation owners and stewards can help to ensure that documentation meets the needs of the team and the organization.
Make documentation a part of your team’s culture
Make it part of your team’s definition of done. Put simply, documentation should be treated like any other deliverable. It should be planned for, budgeted, and reviewed as part of your team’s quality assurance efforts.
When documentation is treated like any other deliverable, it becomes an integral part of the software development process instead of an afterthought.
In conclusion, don’t shoot yourself in the foot. Document today for a happy tomorrow. Write that love letter to your future self. Because the bottom line is that documentation matters. It’s an essential part of the software development process. And by making it a priority in our organizations and by writing good documentation, we can increase the chances of our project, product, and process success.
What other tips do you have for creating, curating, and preserving good documentation? Please share them in the comments below!
