10 tips for better documentation

No readers like this yet.
Typewriter keys in red

Original photo by April Killingsworth. Modified by Rikki Endsley. CC BY-SA 4.0

Last July, after a full week at OKFestival, I managed to find enough energy to attend the Write the Docs EU Berlin Unconference. I only managed to attend one day of the event, but it was worth it because Paul Adams, a free software advocate and Director of Engineering at KDAB, led a discussion in which we came up with rules for helping documentation teams be more productive:

1. Pick a markup style and stick with it

The markup language you pick needs be one that your team thinks works best for all your requirements—especially one that can effortlessly convert from the markup to the output formats. The authoring tool doesn't matter. You can have people use their favorite text editors or editing a wiki. That's up to the team's preference.

2. Pick a toolchain that leads from input to final docs consistently

The key is that the tool needs to produce the output automatically and consistently. Ideally have one command that will regenerate your documentation in all your output formats.

3. Always produce final docs in the formats your users require

Most projects want to end up with an HTML website or a PDF.

4. Define a style guide for your documentation and enforce it

Define everything—language nuances, how to write a title, or pronouns to use throughout the documentation.

5. Always have translations in mind

If you don't need translations now, you still might in the future. Not everybody speaks English. Eventually you will want to have translations. We had folks wanting to translate the documentation into Japanese. It's worth thinking about translations when you pick a markup and toolchain. (See 5 tips for translating documentation.)

6. Base translations off one master set of documents.

If English is the language in which you write documentation, have every other translation based off English so keeping up with changes in documentation is easy.

7. Language-specific style guides

This applies to both programming languages and human languages. Some languages may have a specific pronoun to use when writing official documentation. It's useful for your dev team to define programming language-specific style guides to keep things consistent.

8. Have a QA process for documentation

If you have tutorials in your documentation, they need to have tests so that you know when a code change has broken a tutorial. Additionally, have a documentation review for new documentation. This is particularly important for installation instructions and API documentation, since these are easy to break and frustrating for your end users.

9. Have rules about updating and archival of documentation

If your documentation is old, archive it and remove it from search engine indexing. Have a clear notice when documentation is targeting a new feature that doesn't exist in older versions. If documentation is part of your code base and only updated when a new version is released, have a process to backport documentation that applies to older supported versions.

10. Documentation must have a feedback mechanism.

The easiest way to do this is to have a bug tracker category for documentation.

In conclusion, the most important thing is to build a culture of documentation. Documentation can't be an afterthought—it needs to be part of the release process. There must be a process through which the documentation team can know of new features that need documentation. In fact, if you can find a developer willing to champion the cause of documentation, even better. Although I will note that it is more useful to empower them rather than burden them with documentation, otherwise it may lead to burn out. For instance, don't dump documentation-related bugs on them. Instead, give them authority to block features because they're underdocumented.

Do you have other suggestions? Let us know about them in the comments.

Doc
Dish


This article is part of the Doc Dish column coordinated by Rikki Endsley. To contribute to this column, submit your story idea or contact us.

User profile image.
Nigel is the Gluster CI architect working out of India. He loves open source as it enables him to contribute to an ever-growing intellectual pool of knowledge. He's a Mozilla contributor and when he isn't working he likes to cook or run long distances. Nobody is sure if he actually ever sleeps.

2 Comments

Excellent article! I am working on defining the documentation process for my office. One of the items that consistently comes up is that while no one particularly likes doing documentation in the wiki, everyone wants the documentation in the wiki. I'm not sure if it's due to believing that the wiki is the best place for documentation or other companies have a wiki so we should too. I prefer a markup/down language that can be output in a variety of formats, LaTeX (my current favorite), PDF, HTML, and even wiki markup if needed. Getting other folks on board with that strategy is the current hurdle. Articles like this help quite a bit in my push for a better documentation solution.

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.