Top 10 signs that documentation is craptacular
“Content is an asset worthy of being managed,” says Scott Abel. I agree that good content is an asset. Bad content is a liability. It’s time to talk about the shameful underbelly of technical communication.
There is a lot of really terrible technical documentation out there in the world. It’s incoherent, unhelpful, and/or ugly. This content was “written” without any attention to basic principles of technical communication. When faced with content at this level, it’s probably not wise to attempt implementation of an ultrasophisticated new system. Instead, focus on moving the organization forward a few steps at a time.
Here are the top 10 signs that documentation is craptacular:
10. The documentation voluntarily uses more than one of the following: three-ring binders, change pages, list of effective pages, or numbered headings.
9. There is no style guide.
8. There is no template; or, there is a template but nobody follows it.
7. The technical writers have no subject matter expertise.
6. The technical support organization tells callers to ignore the documentation.
5. Time spent writing is about the same as time spent formatting.
4. The only electronic version of the documentation is a PDF file.
3. In the HTML version of the documentation, tables are delivered as graphics to “preserve the original look and feel.”
2. There is no index; or, the index is unusable.
1. The online version of the documentation contradicts the print version of the documentation.
Step one in fixing a dysfunctional content organization is to establish that good content is valuable to the organization. The exact business case depends on the company, but some common value propositions are the following:
- Good documentation reduces customer support costs (usually by reducing the volume of technical support calls).
- Good documentation increases customer satisfaction.
- Good documentation is required for regulatory compliance.
Addressing the easy fixes
There’s probably some low-hanging fruit that you can fix. Obvious candidates include the following:
- Build a template for your documentation that is attractive
- Require writers to follow the template
- Implement single sourcing for content that should be identical
- Provide a useful electronic version of your content (typically, something HTML-based)
- Provide a useful, well-edited index for your content in all media
If you decide you need help, you know where to find us.