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.
About the author
Ethan
Can you amend number 4 to read, “The only electronic version of the documentation is a PDF or Microsoft Word file?”
Dia
Actually I disagree. Word can be modified. PDF is standard (still many people may not have the $$ to purchase MS Office) and can be read everywhere, for free.
Julia Pond
I would add, “the word count is grossly inflated due to long-winded, discursive style &/or lack of editing, and a template that proscribes hierarchical heading structure and stem sentences (even if they repeat the content of the heading).”
:-/
Jon
I completely agree. I work very hard to try to create standards for our documentation. I keep hoping that someday people will start following them :-P.
Eddie VanArsdall
Wow, “craptacular” perfectly describes the documentation that I have most recently been reviewing and trying to rescue. It conformed perfectly to your ten signs.
Thanks for once again expressing what many of us are thinking.
Val Swisher
Bravo! You are absolutely correct, Sarah. To sign number 10, I’d add: The documentation contains one or more pages that read:
This page intentionally left blank.
And, yes, I still see that nonsense at even my largest customers.
Oh, and let’s not forget having cross-references that are not hot-linked or are linked to the wrong place. Gosh, I think we could easily expand this list to 25 or even 50 craptacular signs….
Roger Sharp
Sarah, you are so worth reading. In addition to #1, I would add, the online version is the exact same thing as the print version. This may be a personal peeve. Online should be quick in & out.
I must admit I fail on #4. Can you, or others, elaborate?
Roger
http://www.dataio.com/Support/TechnicalLibrary.aspx
Inge
1. a PDF file is sequential, means: long docs and you have to go looking for the info you want
2. AFAIK you cannot jump to specific pages
3. Search is possible for one word or one expression only – there’s no “Find me the docs that include those three words.”,like in hypertext media. You also cannot restrict the search to “in the same paragraph” or “on the same page” or “in the same chapter” – you jump from result to result to result …
Sarah O'Keefe
Dieser Artikel ist auch auf Deutsch verfügbar: http://cap-studio.de/wp/index.php/2011/05/die-top-10-merkmale-sub-optimaler-dokumentation/
Sarah O'Keefe
Looks as though this should have been a wiki page as there’s no way we can stick with just 10 items!
@Roger: Not sure I agree that identical print and online is *necessarily* craptacular. If the logic is that some people read print and some people read online, then it makes sense to deliver the same content in both places. I will agree that identically *formatted* print and online is troubling.
re: PDF
As Inge says in #7, PDF is problematic for online use. If the PDF is there to give the reader an opportunity to print the document, that’s fine. But for online browser purposes, it’s not a good choice for the reasons she mentions. There’s the additional problem that PDFs are not very Google-friendly.
Michael O'Neill
Love it Sarah!
I’d just like to add: Your documentation for a single product is split amongst a random assortment of 42 different PDFs and MS Word documents, many with the same generic file name, and no way to search across the entire corpus.
-Michael
Sarah O'Keefe
@Michael: I’d laugh, except I have this feeling you are Not Making That Up.
Side note: The German version of this article also has a few comments. Interestingly, there’s not the general agreement we’re seeing here. In particular, numbered headings are more popular in Germany. I was asked about my reasoning for dissing numbered headings in a private email. Here’s what I said:
1. In the absence of hyperlinks, they can provide a way to navigate the documentation. But we rarely have “absence of hyperlinks” any more.
2. There is an interesting cultural issue here — numbered headings are (still) quite common in German documentation.
3. It’s my opinion that numbered headings make reading less pleasant and more like work. Basically, a UX issue…when you see them, you assume that the doc itself is also going to be unpleasant.
4. There’s a versioning issue — if you number headings and then push out an update of the doc, and then people are using them for navigation, you run into problems. For example, a customer calls tech support and says, “hey, I don’t understand section 2.7.2”. Tech support looks in their (updated) documentation and now they’re talking about two different sections in the doc.
To me, numbered headings scream “this document designed in the late 80s.” And that is rarely a good thing.
Joseph Lorenzini
I found the requirement for an index interesting. Is the argument that you need an index in all scenarios no matter the situation else the documentation is craptastic? I always thought of an index as one tool (very useful one of course) that may or may not be helpful depending on the audience and its needs. After all, an index does no one any good if no one uses it.
Roger Sharp
@Joseph, comment12- for any medium, I always use the index first. It points to 1 or 2 or 3 of the most apropos pages. A search generally finds more pages than I would even consider looking at.
@Sarah- thanks, I now see that Google demands downloading PDFs vs reading online.
@Inge comment7- Yes, you can link (jump) anywhere and back easily in PDFs (if created so). You can link between PDFs, tho I’ve not found it so useful. I’ve also embedded flash videos in PDFs.
Robert Desprez
Hi Sarah,
I love your headline! I once worked at a company that felt that copyedits and technical reviews were unnecessary and expected the writer to produce content that was both technically and grammatically perfect in the first draft. Talk about unreasonable expectations.
Sarah O'Keefe
@Joseph: I don’t think that a lack of an index always equals a bad document. For example, a 50-page tutorial or installation guide is intended to be read sequentially, so indexing would be less necessary. However, if your document is more than about 100 pages, it should probably have an index. And if there is an index, it should be a good index.
Ray Lloyd
Nice to see subject matter expertise at number 7 and this must have been difficult for you to include as you are service providers. You obviously need a good balance between being a dummy and not knowing as many details as the product developers.
Sarah O'Keefe
@Ray: Most of our work is consulting…we build the publishing systems. For that, we need lots of publishing technology expertise — which we have! — but not much in the way of domain expertise. From our point of view, we need to understand datasheets or FDA-controlled documentation in general. We don’t need the expertise to actually write the datasheet or the medical device content for a specific customer — that’s not why people hire us.
We highly recommend using in-house, permanent writers precisely because of the domain knowledge issue.
Paul K. Sholar
“Only online version is PDF.”
One reason that can happen is a need to support precision formatting such as data-intensive tabular content. Today’s XML tool chain can’t publish tabular content that supports formatting available in PDF authoring tools (e.g., FrameMaker). And HTML output simply can’t support complex tables. Result: DITA authors must design simpler tables that don’t as directly reflect the inherent structure of the datasets being presented. And for some cases authors have to create more than one table to present all the data. More work. Slower comprehension of data by readers. Etc.