Good documentation is hard to write.
If you’re shaking your head in disagreement, then you’re either part of the minority that’s expertly written dozens of impeccable documentation, or your documentation really isn’t as good as you think it is.
Good documentation is hard to write because it’s not just about writing down a process. It’s making sure that you are clearly understood by the people for whom you are writing. It’s making sure you are not misinterpreted, that you give all the necessary information and only the necessary information, and that the documentation is effective in fulfilling it’s purpose. When you look at it in this way, good documentation is definitely not easy to write.
Fortunately documentation can always be improved, so even if it’s not so good now, you can always make it better.
Know Your Audience
The first step to creating any type of content is knowing your audience. Are you writing for end-users or other programmers? For newbies or experts? For a small local community or a large and diverse group with outsiders and non-native English speakers? Your audience is the key to determining exactly how your content should be– whether it be a hand-holding tutorial, a comprehensive and highly technical guide or somewhere in between.
If your documentation will cater to a broad and varied audience, it would be better to write for the more inexperienced of the spectrum, or consider writing separate documents. An end-user will prefer an instructional guide that focuses on the interface and not the back-end, while another programmer will want to know about the inner workings of the software and code. For two audience segments like these it would be better to have separate documentation.
Define Your Scope
The second step to writing better documentation is to define your scope. Comprehensive doesn’t always mean better. This is especially true for an end user who just wants a solution to one problem and doesn’t want to have to sift through a mountain of detailed documentation to find it. After you’ve figured out exactly who your audience is, be clear and decide on the appropriate scope of your documentation.
A lot of documentation starts with a “Getting Started” document, and this is a good idea. This informs readers of the things they should know before getting started. It provides an overview of the contents of the documentation as well as what’s not included in the document, and where to find the latter.
Tutorials usually make up the meat of documentation, and these can be accompanied by reference guides that define some of the terms, explain some of the functions and give some examples. Tutorials are more conversational, while reference guides are more factual and impersonal. When writing both however, it’s important to always keep your audience in mind; think about what questions your audience might have after every step and what their current knowledge and skill levels may be.
A large part of your audience will only want to solve one immediate problem (which is perfectly reasonable), and this is where an FAQ (frequently asked questions) or “Cookbook” segment would be most useful. These areas of documentation provide the immediate solutions that end users are looking for. When providing examples just remember to test these beforehand, and to promote best practice, not just the simplest or fastest solution.
Test and Proofread Your Work
Once you’ve written down everything you need to include in your documentation, the last step to is to proofread. This is the part where you make sure that your audience clearly understands what you’ve written. When you proofread, focus not only on what you’re saying but also how you say it.
Apart from basic grammar and spelling, some things you should watch out for when proofreading are unclear, repetitive or “filler” words. You should eliminate these as well as words like “just” or “simply”, as these would imply that the task is really simple when it could be difficult for beginners. Also, refrain from using jargon or if you must, define the terms or link them to their definitions the first time you use them.
Make sure to follow your project or company style guide for documentation if there is one, and check for clarity, correct use of terms, order of words and consistency of terms used.
Some people find it easier to proofread their work by reading it aloud, while others ask more experienced writers or editors to proofread their work for them. Another reliable way of checking if your documentation is any good is by letting someone (preferably someone who represents your audience) try and follow them. See if they can easily follow the instructions and understand the documentation, and get their feedback in order to identify any unclear or missing statements. By doing so you can make your documentation clearer, better and easier for readers to follow.
[Category: Open Source]