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
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?
Larry Kunz
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.
R.B. VanDyke
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!”.
Marie-L. Flacke
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
craig
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.
Alan Pringle
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.
Martin Edic
I think I may have to borrow this! Lol.