The Building Blocks of Solid Documentation
Do you remember the first piece of IKEA furniture you ever tried to assemble? If the experience left a lasting impression, you may have an appreciation for thorough documentation — and an acute understanding of all that can go wrong without it.
Whether you’re producing data, code, an API, or a Swedish-designed bookcase, writing documentation about your product and the processes around it are rarely the most exciting part of development. However, in the long run, solid documentation saves time for individuals and teams, improves collaboration on complex projects, and reduces frustration and confusion for end-users.
There are any number of scenarios where having good documentation can make a difference. As an example, Cornerstone AI’s error detection models produce local interpretations for suspected data issues they discover. When our clients review these flagged observations, we’ve observed time and again that the more knowledge the clients possess about the provenance of their data, the more likely the interpretations for suspected data issues are to immediately resonate with them. In other words, although data will continue to contain erroneous and missing values, a well-informed data team will know where those errors are more likely to appear and be better equipped to recognize when an observation doesn’t make sense in context (and, conversely, when an apparent outlier is actually just fine). One way to improve the transmission of that critical knowledge across your organization is by applying the building blocks below to your documentation practices.
1. Take notes
Just finished implementing a new feature? Dove deep into some code to answer the same question for the second time? Jot down some notes while the “gotchas” and fine-grained details are still fresh in your mind. Don’t like writing? Record a voice memo, or if it’s applicable, capture a few screenshots or a short video of your screen. Even a hand-sketched diagram is worth a thousand words. Generating a small amount of information-rich content that can be built upon later should be low effort but high reward.
2. Fill in the gaps
When it becomes clear that formal documentation on a topic would be valuable, expand your notes into a comprehensible document. Be sure to include steps and details that may seem obvious to you but may not be so obvious to a future reader, such as prerequisite software to install or equipment to procure. The goals are to provide sufficient detail such that any processes or examples are fully reproducible by either your future self or a team member, and to communicate the information in such a way that it can be easily understood by motivated individuals.
3. Enable discoverability
Publish this fully-fledged piece of documentation somewhere it can be easily found by anyone seeking the information it contains, and where the information it contains can be easily searched, as well. For instance, a team member who needs to call a newly-added API endpoint should be able to easily locate the API documentation and, subsequently, quickly find a working, fully reproducible example call for the endpoint of interest within that documentation.
When choosing a solution to enable documentation sharing at your organization, work first with the tools already at your disposal. Do you already have a system for sharing documents, data, or code that is searchable and accessible to everyone? Start there. Add metadocumentation to onboarding reference materials, listing for new hires where documentation on various topics can be found. This is particularly useful if documentation is distributed across several platforms.
Pain points can guide subsequent assessments of whether different or more specialized tools would improve collaboration. For example, as their documentation approach evolves and is optimized over time, some organizations may choose to consolidate as much as possible into a central knowledge management system, whereas others may opt for a more localized solution (e.g. code documentation lives with code, data documentation lives with data, and so on), while still others may discover that specialized documentation platforms meet their needs best. Regardless of the particular solutions utilized, communication between team members is important for both a shared understanding of best practices and their consistent application.
4. Democratize improvements
Accessibility and discoverability are essential for documentation to be broadly useful, but alone are not sufficient to improve its quality. However, by empowering and encouraging team members to contribute to all documentation — including documents they didn’t author — critical details can be added or corrected. For instance, when documenting examples or step-by-step processes, small but necessary steps are often unintentionally omitted from the first draft, but are caught as soon as the first reader attempts to apply what’s written. Even small omissions like these can lead to confusion and time lost by the reader as they try to piece together the writer’s intentions. If everyone is empowered to update documentation, issues like these can be solved immediately upon discovery.
5. Keep it updated
Rarely is documentation a one-and-done undertaking. This is particularly true when it concerns code or APIs under active development, but is also the case for any subject matter about which new learnings may surface over time. Documentation for static datasets in particular tends to fall into the latter category; the data itself isn’t changing, after all, but key details about it may trickle in over time. To retain the value of a documentation investment over time, it should be composed of living documents and a long-term commitment should be made to its upkeep by the organization as a whole.
Beyond democratization of updates, there are other practices that can improve the likelihood of frequently-used documentation staying relatively current. Most importantly, adopt the habit of updating documentation concurrently with code, infrastructure, or process updates. For example, if code documentation lives alongside code, update documentation in the same pull request as the code change that necessitates them. An item can be added to pull request or release checklists to remind team members to update impacted documentation. Additionally, ensure that a “last updated” date is prominently attached to all documentation. Use that date to flag documents for review and revision — or removal — when they reach an advanced age, or budget a couple of hours biannually for “documentation grooming.”
In short: start by documenting essential details for yourself, flesh them out until they’re usable by others, share the result, and finally distribute the responsibility of improvements and updates across the team. Happy documenting!
Additional Resources
Interested in building on the foundational documentation practices above, or reading more about best practices for your particular use case? Some additional resources are listed below.
- Documentation Guide : A robust guide to software documentation best practices published by Write the Docs, “a global community of people who care about documentation.”
- The Hitchhiker’s Guide to Documentation: An easy-to-read guide outlining best practices for technical documentation with particular focus on organizations.
- The eight rules of good documentation : Adapted from Collaborative Web Development by Adam D. Scott, this article briefly outlines 8 characteristics of great software documentation.
- Importance of Documentation and How to Ace Internal documentation, both from Atlassian, respectively provide motivation and general-purpose best practices for organizational documentation, both generally and within Confluence.
- In 7 tips for starting, writing and maintaining your documentation, Curtis Stanier shares the tips he follows as a Director of Product to produce high-quality documentation for his team’s product suite.
