Reality check: Writing for scannability and localization

Writing documentation for usability and scannability has several effects, as I’ve recently found out.  After recapping some principles, I share some anecdotal feedback on scannable documentation I’ve written.

Writing scannable documentation

[These principles first appeared in my recent post “Do you know Time?”]

Documentation can be more successful when we make it easy on our users to use and apply it quickly:

• Clear topic structure helps users to orient themselves and learn the lay of the land quickly
  • Separate topics by type, whether it’s concept, task or reference.
  • Keep self-contained topics short and concise.
  • Insert indicative links to related topics.
  • Imply the topic type in the heading:
    • Nouns lead in headings of concepts
    • Imperatives lead in headings of tasks
    • Names of commands, variables, etc. lead in headings of reference topics
• Parallelism (giving sentences of similar purpose a similar structure) improves scannability, comprehension and retention.
  • Start each mandatory step in a procedure with an imperative verb.
  • Start each optional step with “Optionally”, followed by an imperative.
  • Front-load your sentences, so the beginning of a paragraph indicates what the paragraph is about.

Reality check

I’ve recently written a user manual that applies these principles. It’s a guide for implementors to set up and configure a complex, customizable workflow of about two dozen steps. In that workflow, users can first import data from several sources, then validate the data, then process it, inspect and validate the results and create reports. So I have about two dozen sections that outline how to configure each step and how to test the configuration.

Here’s some of the feedback I’ve gotten on that manual – and my comments:

The documentation is quicker to navigate and easier to read.

Thanks – that was my intention, and I’m glad that it seems to work. 🙂

All those links to related topics are giving me the run-around. I want to know how to do stuff, not turn pages back and forth!

This is a reaction to topic-based writing, and I would think it fades away once users have gotten used to self-contained topics. There is actually an advantage to this: Users may leaf around a little more at first, but overall, they’ll spend less time searching and more time finding because it’s clearer what can be found elsewhere and what can’t.

I think this makes users more confident, too: If something is missing, they can move on to other means of support quickly. It’s bad enough if the documentation is possibly incomplete, but it’s worse if users get frustrated not knowing whether information is missing or somewhere else. (That last situation sounds like Donald Rumsfeld’s “unknown unknowns”…)

The structure makes the instructions repetitive and boring.

True enough, that’s the downside. What’s easy to grasp when reading one or two topics becomes boring when you read the complete manual.

The best answer I can offer is that I’d rather be clear and concise than self-servingly funny. (Or should documentation add fun to what is essentially an arduous setup process in a professional piece of software?)

The headings look weird when translated.

Ah, yes, good point! On the one hand, the translation is neither less nor more formulaic than the original manual. On the other hand, it does look weird when the translation focuses more on conventions of the target language than on scannability.

German is about as big on nouns as English is on verbs. So an English imperative in a heading “Configure the data import step” easily becomes a noun in German: “Konfiguration des Schrittes Datenimport”. (And I do need the “step” in there to distinguish it from the non-workflow “task” – it’s an intricate system…) Imagine several parallel entries “Konfiguration des Schrittes…” in the table of contents, and you have repetitive boredom alright.

However, you can also “front-load” such headings: Write “Datenimport-Schritt konfigurieren”, and the scannable unique part comes first. Writing for scannability benefits when translators know the applied principles…

Your turn

What’s your experience? Does writing for scannability work? Do users appreciate it? What issues have you encountered when localizing structured or fomulaic writing?

Advertisement