You won’t find these rules anywhere else.
4 Rules No One Tells You About Documentation
You’ve got your software packaged and ready to go. Now what about the docs?
Documentation has the ability to make or break software. Your users will go to the documentation to find their answers and if they can’t find it, they won’t be your users for long. Following these 4 rules will help assure your documentation keeps your customers around so you can focus on making the best software product.
Keep it Simple
Keep it Simple should be the mantra of all writers. Sure, you could have comprehensive documentation that covers every possible scenario but, your users will never find what they are looking for. Keeping it simple is a balance of giving the reader exactly what they want. Adding too much will make the documents feel too boring and adding too little will create a headache for your support team.
A good rule to follow is to keep your documents as few as possible with as little overlap as possible. This will matter as the product grows and changes. If you write simple documentation, you won’t need to go back and adjust it every time your product updates.
Version Control
The best way to adapt to version controlled documentation is to treat the docs like code. Long were the days when changes to documentation were untraceable and the final product was named, “Final-version”, “Final-version-01”, and when you were really sure, “Final-Final-version_use_this_one”. With distributed version control systems like Git and SVN, you can track changes and have multiple people working on the documentation at once, all with a commit history. The idea of applying software tools and techniques will help as your documentation grows.
Easy to Publish
Invest into a good tool-chain so your writers can make changes, updates, and revisions fast. Writers should be writing and not spending 45 minutes configuring the tool chain so they can fix a typo left behind by the developer’s contribution. Every company is going to be different, so spending time setting up the tools for the writer will pay off in the long run.
Your writers should be writing in DITA XML, AsciiDocs, or some version Markdown, so that the publishing time is quick and easy. Stay away from publishing PDFs, as they quickly become outdated. Using DITA XML, AsciiDocs, or another Markdown language will ensure that the text is lightweight and can be transformed into a myriad of other languages to future proof your documentation.
Make Your Docs Easy to Find
If your users can’t find your documentation, what good are the docs? Having a robust search engine, using metadata tags in the docs, and having a clean table of contents will all help you improve your customers experience.
Consider using Google Analytics, or the like, to track where your traffic is coming from. Are your users finding what they need by searching the documentation, are there internal links driving traffic, or are they using a google search function to find what they need. Also, consider why some pages aren’t getting any traffic: it might be that it can’t be found.
I hope you find these rules helpful and implement what works best for you and your team. If this article helped and you’d like to learn more about technical writing, consider joining a technical writing community.