Principles of Effective Documentation
Writing documentation isn't glamorous, but it's critical to building effective teams. It doesn't matter what role you find yourself in, good teams care about their documentation and everybody is responsible for it.
The following is output from my time working with various clients at Method:
#1 You can't make people read the docs -- write it anyways
Dedicating immense effort to documentation may not always lead to its immediate use, but it's still worthwhile. The alternative leads to inefficiencies and unclear processes which equate to lost time. Overcoming the challenge of getting an organization to use and be aware of documentation is a minor hurdle compared to the difficulties presented by unwritten, decentralized processes and procedures. Prioritize creating and centralizing documentation to streamline organizational operations.
#2 Make note of things you find yourself repeating
A useful strategy for adding to your documentation is to observe the questions and conversations you often repeat. If a certain process or implementation is simple yet frequently asked about, it's a prime candidate for documentation. Next time you're in a situation like this, make that the final repetition by writing it down so your team can easily find it. This not only saves you from reiterating the same points but also enables your team to focus on higher-priority items.
#3 Writing highlights deficiencies and sparks discussion
Documenting processes doesn't solve all team challenges, but it helps scrutinize workflows. The inability to describe a task or process in a few paragraphs could indicate a flawed understanding. This opportunity can be used to innovate and drive improvement within the organization. Change in large organizations is gradual, and documentation serves as a starting point for important discussions.
#4 Complimentary, not comprehensive
Good documentation should be supplemental, assuming a basic understanding of the topic by the reader. The approach is similar to any intermediate-level course you'd find online...it presumes some prior knowledge. Including too many details can lead to unnecessary complexity, making the material less clear and therefore less consumable. Effective documentation aims at providing enough information to enhance the reader's independence in the subject, without being overly exhaustive.
#5 Clarify the what and why
The frustration of cumbersome documentation – unformatted, contextless, and hard to understand – is common. A practical solution is to include an "Objective" section at the beginning of each major section. This approach helps the writer clarify the benefits and relevance of the document to the reader. Though it may seem trivial, providing clear objectives and reasons for reading the document's purpose enhances its usability and value.
#6 Documentation as a product
While not a product in the traditional sense, documentation is still a product, serving its readers. If it doesn't offer a good experience, it will be underutilized. Good documentation, like any well-designed experience, should be accessible. Simple enhancements like color coding, proper spacing, and the inclusion of screenshots and external links can greatly improve its utility, making the content easier to digest and more effective for its consumers.