Writing effective documentation

Do you struggle to find the answers you need from your documentation? Have you ever said “This documentation page sucks” or complained about your documentation platform in general?

If so, you might be excited to know that the solution to your problems is within your power to fix! From comments in code, to internal documentation, to writing emails to your colleagues - there are some quick best practices that can help you be more effective at communicating.

My quick tips

1. Always have a table of contents
2. Number your sections and use section headers appropriately so that folks can keep track of where they are in the page 
3. Avoid long-winded (or even short winded) explanations about history or conversational asides anywhere that you are sharing how-to or instructions. This type of information is very distracting and can even be confusing to readers, who will be unaware about the relevance & significance to what they need to know. 
1. If you feel compelled to include such content in your documentation, then it can be placed in an Appendix A section at the bottom.
4. As an alternative to several repetitive sub-sections, consider if your information could be better presented via a Table.
5. Use numbered Lists.
6. If you have a list with multiple sub-lists, then it’s likely that you need to create new sections for each of those sub-lists. Your top level section can have a high level list – but don’t forget, so does your Table of Contents!
7. Stay focused on the type of information you are sharing. Is this a Runbook or an instructional page? I.e. is the reader looking to learn about a feature so they can add new code to it, or are they just solving a problem with no desire to ever think about this again?

Learn More!

I did some searching in Google and thought this post covers a lot of useful topics

1. Writing effective documentation - the Lead Developer Berlin 2019 | Beth Aitman (there’s also a YouTube video for people who prefer video).
2. She links to another page, Content design: planning, writing and managing content , which I found to be amazing, but has possibly more information to peruse than you’re ready for.

Give back!

Improving at this skill set will make you a stronger engineer, and it will help your team be better too. If you have your own thoughts to share, please comment on this post!