Good documentation is useful, great documentation is empowering. We should practice towards great documentation.
Working on any product involves using, contributing to or creating documentation. For me the analogy that works is that these are paths that are either established or need to be established so that we get the end destination faster.
The quality of all this matters because it can become a catalyst, a resource that can accelerate others repeatedly.
I'm still working on my practice, but here are three things that I've received good feedback on which you may like to explore.
Add context at the start
Set the scene of what the documentation is about or even what it aims to convey.
For example:
This page captures information about our data model, it aims to show it's structure and provide an overview of it's core features. For questions contact x team.
This helps by:
- Saving users time if it isn't relevant
- Setting expectations of what's ahead
- Providing a refresher context if you're revisiting
Link to related items
There are going to be other items that connect topically and are valuable for readers to move onto.
Placing links that connect to related things helps by:
- Embedding the inherent knowledge of the creator to save time for future visitors
- Signposting to other items that are useful for next steps
- Creating a structure that integrates itself into a wider set of knowledge
Clear language and a navigable structure
Everyone has different needs and in context of our documentation some might only need a small section, others might need everything.
Writing concisely and with embedded navigation helps by:
- Reducing cognitive load by clearly sectioning the core concepts
- Improving search-ability inside the documentation
- Creating clear explanations in a structure that could be expanded on
By working with a mindset of making the paths better can help all those using them in the future.
If you have any tips conducive to helping others please, do get in touch.