How (not) to use documentation checklists

Checklists can be great aids, but they won’t guarantee that you create good and complete documentation. – That’s my experience, and I’d appreciate your input whether you agree or not.

The Valuable Content Checklist

Content strategist Ahava Leibtag published the “essential Creating Valuable Content Checklist (TM)” last month, along with a step-by-step guide:

With this checklist, you can ensure that your web content is

  • Findable – because it has a headline, title, keywords, links, etc.
  • Readable – because uses chunking, bulleted and numberes lists, etc.
  • Understandable – because addresses user personas and their proficiencies, context, etc.
  • Actionable – because it gives readers incentive to act, comment, share, etc.
  • Shareable – because it gives readers a reason and the means to share, etc.

I think Leibtag’s checklist covers a lot of essential features of good documentation, so it should also work well for technical communications. (The book Developing Quality Technical Information by Gretchen Hargis, et al., also contains great checklists for documentation.) But then I had second thoughts…

Clear and simple

The good thing about checklists is that the best ones are clear and easy to use. They remind you of things you may forget otherwise. One of the most impressive recent examples of their benefits has been in medicine: Peter Pronovost’s checklists have shown to improve the delivery of critical care. (Atul Gawande reports on them in the New Yorker of 10 Dec 2007.)

Seductively simplifying

The bad thing about checklists is that they are so clear and simple, it can be seductive to rely on them for things they cannot do. You can check off all items on your checklist, but you may still create

  • Incomplete documentation, when you’ve missed a sub-topic, keywords, links, a persona or a use case.
  • Useless or bad documentation, when you describe an unintended or even dangerous way of using the product.

In other words: You get what you measure. If checklists are your tool, you will get formally complete documentation, which may or may not be helpful to customers.

As simple as possible, but no simpler

I think the solution lies in the quote attributed to Albert Einstein: “Everything should be made as simple as possible, but no simpler.” That’s good advice for documentation in general, and for checklists in particular. This means to me:

  • Use checklists only after writing a topic to verify that it satisfies formal completeness standards.
  • Avoid checklists while writing a topic when I focus on content and quality, specifically on usefulness and applicability for users or personas.

I also appreciate that structured writing already separates layout and content, so I can use my “freed-up brain cycles” to focus on content and not go on auto-pilot and simply fill in topics with bits and pieces while ticking off check boxes.

Your turn

Do you think checklists do more good or harm in technical communications? How do you use them to make sure they improve your documentation, but don’t compromise it? Please leave a comment.

Advertisements

4 Responses

  1. Good points, Kai.

    I have never found anything better than a checklist to help me make sure that my work looks good and is ready to publish. But a checklist only asks a consistent set of yes/no questions – did you do this? What about this and this? It can’t help with things that are specific to a given topic.

    For topic-specific information, I make a spreadsheet. This lets me capture important information about each topic – intended audience, product changes that will affect the topic, subject-matter expert, tricky things that customers will need to know, etc. After I collect this information, I can work quickly while still being thorough.

    • Thanks, Karen! Yes, I can totally see how a content spreadsheet is the ideal companion to a checklist. I’ll have to try to get the two to play together!

  2. I start a checklist, find it getting longer and longer and longer, and then I look for ways to automate parts of it. The checklist is acting like a spec for a computer program.

    • Thanks, Steve, that’s a very good idea to get good and efficient use out of checklists and to keep your brain free for important stuff such as actual contents.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: