Top 10 signs that your documentation is craptacular, 2017 edition

Sarah O'Keefe / Opinion5 Comments

Cake wrecks...

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?

About the Author

Sarah O'Keefe

Twitter

Content strategy consultant and founder of Scriptorium Publishing. Bilingual English-German, voracious reader, water sports, knitting, and college basketball (go Blue Devils!). Aversions to raw tomatoes, eggplant, and checked baggage.

5 Comments on “Top 10 signs that your documentation is craptacular, 2017 edition”

  1. Along the lines of #6: users ask questions and swap how-to information on third-party websites….and those sites draw more traffic than the “official” documentation site.

  2. Documentation is designed then developed in the complete absence of usability testing with users / readers. Indeed, if a technical writer tries to collect design or usabilty *data* from users they’re generally told to “quit wasting time and write something!”.

  3. Point (5) – Technical writers spend at least 40% of their time _formatting_
    Points (3) and (4) – “Findability” is not on technical writers’ agenda (web, mobile and paper)
    Point (00) – Noboy cares about user and task analysis. “user-oriented”, “user satisfaction”, “useful information”, etc. are FOREIGN Words to Technical Authors

    The above is applicable to Continental Europe

  4. 7) – What?

    Why does a technical writer need to be an expert if they have access to experts? The curse of knowledge is one of the main causes of poor documentation.

    1. Knowledge (or lack thereof!) cuts both ways. A total lack of technical expertise can also lead to superficial documentation (Select Menu > Menu choice to do X) that doesn’t address real-world applications.

Leave a Reply

Your email address will not be published. Required fields are marked *