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.

7 Responses

  1. I try to remove adverbs that slow down the reader. Keep it short.

  2. One writing teacher I had in college, said users of documentation read it the first time tutorially, to learn what to do, and the order of the steps required to do it.

    After that, they use the help or the doument as a reference, seeking a key piece of information to do what they want to do. For that, our job is to give them as many “handles” to help them find that missing fact or step they need as fast as they can: the TOC, an index, heads and subheads, header or footer tags, and links or bookmarks. They give us a very short time span –a couple of minutes– in which to locate the info they want before they will turn to another source.

    • Thanks, techquestioner. Yes, indeed, the time we have to make a good impression with our documentation is short. And what’s worse, we only get one chance.

      Another way to address the use case you mention is to provide (and help the user to navigate) different doc formats, for example, tutorials and reference information.

  3. […] Weber on time and how to use it as a tech […]

  4. […] Favorite Posts Portable apps for tech writersContent is a service, not a productResearch about ragged-right over justified alignmentReality check: Writing for scannability and localizationDo you know Time? […]

  5. […] “Do you know Time?“ about parallelism and writing for speed […]

Leave a Reply

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

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

Google photo

You are commenting using your Google 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 )

Connecting to %s

%d bloggers like this: