Skip to main content
May 1, 2017

Top 10 signs that your documentation is craptacular, 2017 edition

This post is part of Scriptorium’s 20th anniversary celebration.

Way back in 2011, I published the first edition of this list. It’s interesting to see how much has changed since then.

Back in 2011, list highlights included the following:

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.
1. The online version of the documentation contradicts the print version of the documentation.

Here is the updated 2017 edition. The items in boldface are unchanged from the original list. Items in italics are updated, but related to the original point.

Top 10 signs your documentation is craptacular, 2017 edition

Cake wrecks...

Some things, you just can’t improve on // flickr: justinbaeder


10. Technical content is siloed from other corporate resources, like support content, training content, and marketing content.

9. Content uses inconsistent terminology, formatting, and style.

8. Content does not follow basic best practices for localization readiness.

7. The technical writers have no subject matter expertise.

6. The technical support organization has a private copy of the technical content in which they have made updates and corrections.

5. Authors spend more than 10% of their time on formatting tasks.

4. Information delivered online is not usable on a mobile device.

3. Information is not findable via web search.

2. Information is not available online.

1. Information is incorrect or out of date and contradicted by other corporate content and by third-party resources.

Many of these points are addressed in the discussion of minimum viable content.

What do you think? Are there other factors that belong on my top 10 list?