Do you ever read documentation and think, “What the hell is this? Who wrote this garbage?” or “Well, this is out of date; I’ll go elsewhere.”
If you’re like me, you’ve most likely stumbled on a project where the previous developers left behind a jumble of code without documentation or documentation that was an extension of their to-do list or complaints about the status quo. It feels like even making a start takes weeks.
Conversely, you’ve probably experienced the joy of inheriting a well-documented project or consuming an API with blissful documentation. As a result, you’ve been able to dive in and contribute meaningful work from day one.
They say it’s inevitable; once you write documentation, it’s outdated. But that doesn’t mean we can’t make a reflection of past events effective. I wanted to outline a few tactics for creating and keeping effective documentation in this article.
What is Effective Documentation
Effective documentation:
Is written for the reader
Uses clear and concise language
Includes context, examples, and visuals
Is kept up-to-date
Encourages feedback
Below are a few tactics that you can use to help achieve this
📂🔍Locate documentation closer to work
Have you ever corrected a typo or comment just because you saw it while editing some code? Kudos.
Documentation closer to your work is far more likely to be read, checked, re-read, updated and sought after. Having the full picture where you work reduces application or context-switching, making it easier to stay focused and productive.
A development team’s code should be self-documenting, using clear variable and function names and strict typing or type hints. Code can easily explain the What and How, and AI can help decipher even the most complex code, leaving code comments to explain the “Why.”
Process documentation is the same, whether using a tool or creating tools. Finding ways to integrate documentation into workflow allows it to be kept up to date and accessed within the work environment. Wikis are great for documentation, and many can be easily integrated into other tools or linked using smart links.
🟨🟪🟥 Know you, and your audience
Rather than only considering who will be reading your documentation in the future, use the concepts from Team Topologies to determine your team role and how you can tailor the language and level of detail depending on the type of reader.
You’re likely part of a complex subsystem team when writing and documenting specialised systems. The terminology and concepts may require prior knowledge or training. Remember, though, that enabling or stream-aligned teams may require a version of your documentation, so summarise detailed concepts in clearer language and visuals.
On the other hand, if you’re on a stream-aligned team, your documentation should be written for a more general audience, aiming for quick understanding and easy consumption. You’ll need to explain some concepts briefly but refer readers to additional documentation for further detail.
Giving the reader the option to read more, should they need to, is better than overloading them from the onset. Suggesting previous, next, or further topics in and around the details of your article can be helpful.
⏳⌛Set a Time To Live
“This documentation will self-destruct in 5 seconds.”
Okay, so I don’t mean to delete documentation automatically, but establishing a Time to Live (TTL) or review cycle for documentation based on factors such as the rate of change of work or process, industry, employees, or customers can be very useful. Review cycles could be quarterly, semi-annual, or annual, for example.
The key here is implementing a flagging system that automatically marks or highlights documents for review as they approach their TTL or review date. Such a flagging system should create reminders or notifications to alert document owners or team members.
For code, this can be done very easily through CI/CD and various markdown metaformats, for example. Your team could even have tests that fail depending on documentation being within their expiry date.