Roundup: Good documentation practices
A quick recap of good documentation practices to make your content shine
We’re almost done, but before signing off I wanted to quickly round-up the best practices for great documentation that we’ve talked about over the last few pages. This is your TL;DR, if you will.
TL;DR — How to write good documentation
Write for your audience – Think carefully about who will be reading your content, and make sure your writing includes the right amount of detail for them. This is especially if your audience is very broad, as you need to think about how to cater to different levels of expertise.
Write like you speak – Great written content sounds like something you would say out loud. If in doubt, read your documentation aloud and edit any parts that trip you up.
Include the right information in your technical documentation – There are a few common technical documentation elements — such as code samples and installation instructions — that people will find really useful in your docs. Try to include as many as you can.
Communicate technical information clearly – If you’re writing about complex topics, it’s always important to keep your content simple so it’s as simple as possible to find and digest. It shows you value your readers’ time.
Start with a template – Don’t worry about the blank page. Kick off with a template (GitBook has some handy ones built-in) and at the very least they’ll serve as inspiration for your work.
Write for SEO – Make it easier to find your docs by writing with SEO in mind. Want a super-fast rundown? Head back to my quick SEO tips to improve your ranking.
Think carefully about your page structure – With an online tool like GitBook, you can use different content blocks to display different information. You can also organize your pages into groups (and add sub-pages). Nifty!
Customize your content – Give your documentation a unique look and feel to make your content feel more custom.
Update your content regularly – Your documentation is never really ‘done’. Make sure you update it regularly, to show your users that you’re actively maintaining your product or code, or address common questions.
Remember, if you want to see some great examples of documentation and other content done really well, go take a look at GitBook’s Content Library. It gathers together great docs, guides, company handbooks and more — which are great reference materials while you’re writing!
Last updated