Much like the other great searches in the world (Bigfoot, Amelia Earhart, missing socks in the dryer) people are constantly on the lookout for something else which often proves elusive: good documentation.
We know it when we use it, read it, skim it. We know it when it’s presented to us. We also know when the documentation we’re using isn’t in that category; when it leaves us questioning, unable to find the answers we need. In many cases this is the easier experience to define: when the documentation just isn’t cutting it.
With that in mind it begs the question, what are the qualities of good documentation? If we can readily identify when the quality isn’t to our standards, it should help to define what we’re actually looking for. The following are aspects which define good documentation.
Documentation should be easy to find
This is obvious but often ignored, sometimes out of proprietary concerns, sometimes from neglect. But the fact is it’s important that customers be able to easily find and access the documentation. There should be pointers to it from the most commonly used areas of the site. If the documentation is for developers the link should be included on the main developer page.
In almost all cases the documentation should not be hidden or placed behind a password protected gateway. While this may be dicey for government agencies with national security concerns, the fact remains that in most cases you shouldn’t need mad hacking skills to crack the code and find the documentation. As creators of impressive products we want to get the word out and instruct people on how to use them. A big part of this is showing them where the information is. Think of it as a support agent which works 24×7, answering questions while reducing calls to customer support. Information should be free and distributed.
Documentation should be simple and present a logical workflow
When the reader first views the documentation it shouldn’t cause stress. Including too much information at once causes thoughts of, “this is hard” or “I’ll look at this when I have more time” which in many cases never happens. Good structure and layout can alleviate this. The documentation should be cleanly laid out with major tasks prominently displayed. Supported platforms should each have their own section containing their own specific instructions. The sections and instructions themselves should create a logical workflow. It should be clear how each task flows into the next, or if not, why. If there are standalone tasks that can be done anytime with no dependencies that should be made clear.
Bullseye The Most Common Tasks
All products have tasks which must be done, and many have tasks which present challenges. These are examples of prime candidates for inclusion on the front page of the documentation. Even if the front page is simply a Table Of Contents of available topics, there should be a way to highlight the tasks which get the most attention. After all, if most customers use a product’s documentation to help with installation or configuration, it’s in the best interest of the company to make that information easy to find and solve their issues.
Avoid the Fringe
Tasks should be presented as simply as possible using the straightest possible path. This means understanding the basic scenario and how the steps are carried out and documenting it. While deviations can (and do) exist in many company’s environments, understand that they can’t all be included in the documentation. Attempting this causes information overload and unnecessary information which won’t apply to most users. The solution? Create separate documents for these cases such as white papers or tutorials.
Always Include WHY
When performing a task, there’s nothing worse than looking at the information unable to determine if all the steps pertain to you. Tasks without context cause confusion. Each task should clearly have the reason for it to be performed. In some cases it may not apply to some users, such as a prerequisite for other software they do not use. Including the context behind the steps allows users to know all the details and quickly filter out those that don’t apply to their environment.
Examples Matter
Good conceptual information and steps are crucial to technical documentation. However the icing on the cake are examples. Examples can make the information real and tangible, using the required input and values to demonstrate the implementation. These examples can then be used by the customer, who may simply change the values for their needs. As a result, the customer has a high degree of assurance with their code and has saved development time.
In many cases a live testing area can also prove invaluable. This is an area on the website where a customer pastes code in and it’s validated or run immediately. Especially effective with simple code such as REST APIs, this allows immediate code testing with no compile step. Combining good examples with a live testing area provides the perfect combination of information, assistance and results.
