Introduction
Your guide to writing, editing and structuring the best documentation — plus tips on how to make your content shine in GitBook
Anyone can write documentation. All you have to do is explain your product, your tool, or the ways you work. Nobody knows it better than you, so just start typing and you’ll be done in no time… right?
Well, yes! And no. Ultimately, some documentation is always better than no documentation. Even poor documentation is better for a user than searching fruitlessly for the information they need. So yes, anyone can write documentation. But writing it well? That takes a bit more effort.
In this guide, I'll walk you through the essentials of great documentation — starting with the foundations of good writing, and then discussing how you can combine those with great structure and maintenance. By the end, you’ll have everything you need write documentation that will not just help your users, but keep them coming back — and maybe even make them recommend your work to a friend.
Why write documentation?
There are plenty of reasons why writing documentation is a good idea. Firstly, you want people to use your product or code, and have enough information to contribute back to it, if they wish. And of course, helping out your users makes them happier and improves their experience!
This can push your sales or user numbers more than you’d think — but great docs can also save you or your support team time answering user questions.
Oh, and you should never underestimate how much you may rely on your own documentation down the line. In 12 months time, when you want to make a change or pick up where you left off, you’ll soon realise you’ve forgotten literally everything you did and why you did it. And then you’ll curse your past self for not writing great documentation at the time.
TL;DR — why write documentation?
To help people use your product or code
To give people enough information to contribute to your code
To improve your user experience
To save time for your support team
To serve as a reference point for yourself in future, when you come to make changes to your product or code.
With all that in mind, let’s dive in!
Last updated