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.
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.
2 Comments