Rules, rules, and more rules When I was at FSOSS recently, I had lunch with an interesting mix of people — including a student in the Seneca College technical communications course and a couple of system administrators. One thing that they had in common was that they’d all attended my presentation. Maybe technical writing has a lot more appeal than I thought …

Anyway, one of the system administrators mentioned some documentation that he and his team were putting together. It was a set of descriptions for literally thousands of test cases. The descriptions are accessible online — click a link when an error occurs and you’re taken to the test case that’s related to the problem.

It turns out that he’d laid out the documentation as I would have: in a table, with headings in the left column and the information in the right column. The problem, though, was that this documentation needed to be very concise. The people using it needed to be able to scan it within 20 or so seconds in order to diagnose and troubleshoot the problem. While my presentation at FSOSS discussed streamlining documentation, it definitely didn’t go far enough for that situation.

I remembered something that Tom Johnson recently wrote:

[T]he user just wants a brief, clear explanation of a concept or task. The user will glance and skim — reading behaviors hardly worthy of the elitist grammarian who argues the finer points of “which” versus “that” in restrictive clauses.

If there every was a situation in which readers would need to be able to scan and skim, this was it.

In a case like this, you don’t need documentation made up of perfectly-chosen words and phrases. Instead, you need something that can be easily scanned, easily understood, and easily digested. Documentation that distills the main points quickly. Far more quickly than even the kind of minimalist documentation that I encourage can.

Something that radically deviated from the norms of documentation was needed. My advice? Write in sentence fragments. Yes, I actually said that. In the situation that was described to me, that was really the only solution to make the documentation easy to scan. Bullet lists and short, grammatically correct sentences wouldn’t be brief enough.

What I mentioned doing was:

  • As I mentioned earlier, don’t be afraid to write in sentence fragments
  • Get rid of any articles — a and the will slow the reader down
  • Use symbols like / and & and + to replace words like or and and
  • Use developer speak — for example, based on system status — to make things shorter

Thoughts? Feel free to leave a comment.

Photo credit: chelle from morguefile.com

  • Share/Bookmark
Print

Related posts:

  1. Four rules for good documentation
  2. Taking a break
  3. Essential documents for a software project

Related Posts