Do you know Time?

We know what IT is and we know TIME and we know that everything is really FINE.

… says Dean Moriarty/Neal Cassady in Jack Kerouac’s On the Road (part 3, ch. 5). Now, Neal was known for a lot of things, but tech writing wasn’t one of them. Still, I believe we writers, too, can know time, so I’ll look at different aspects of time and how they affect the success of our documentation.

Time to produce
This one is obvious: There’s the time to write and produce our deliverables until we have to get them out the door, when the deadline approaches or the money runs out.

Time to consume
Whether our documentation is successful also depends on how much time our users need to find, read and apply it. I’ve seen help where I couldn’t find answers and manuals where I couldn’t tell if a poorly structured 20-page chapter would actually be helpful.

This is when users turn to search engines and forums instead of documentation. As Scott Abel points out: “Users don’t care where they get help from – they just want to find the answer to their problem when they encounter it”, and if it’s from another user at 2:30 a.m.

Knowing time
Users don’t only want help “now”, they also need to know time – literally, as I’ve learned from two incidents last week:

I was watching a documentation screencast with excellent contents. But the Flash player had only a general progress bar, with no indication of remaining time and poor navigation within the playing film. I found it so distracting, I would’ve gladly traded in the benefit of seeing the action on the screen for better orientation and pacing on the written page. Knowing time helps to orient users to where they are.

Then I went to a Pecha Kucha night – and the place was packed. It sounds like a strange concept: Would you go and see a dozen or so PowerPoint presentations on topics you didn’t know in advance by artists and designers you probably not know? Loads of people do – because each presentation is 20 slides for 20 seconds each. 6:40 minutes, and it’s over. You spot a bad one in the first 10 seconds? You take a leak, get another beer and are back in time for the next one… The same idea makes the 22-minute meeting so intriguing. Knowing time helps to focus attention.

Writing for time
So I believe our documentation can be more successful when we make it easy on our users to use and apply it quickly. And there’s a lot we can do towards that end:

• 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.
• Minimalism trusts users to figure out some stuff on their own (quotes from John M. Carroll’s The Nurnberg Funnel)
  • Address users with realistic task topics
  • “Help users get started fast”
  • “Rely on the user to think and improvise”

But beware…
… and heed Henry David Thoreau, who gives better advice to writers than Neal Cassady:

Not that the story need be long, but it will take a long while to make it short.

Which aspects of time do you watch out for when writing documentation? Feel free to leave a comment.

Advertisement