What’s in a (serial) comma?

An example of a missing serial comma got tweeted my way which was too good to be true:

Among those interviewed were his two ex-wives, Kris Kristofferson and Robert Duvall.

And here’s the guy who was married to both, Kris and Robert… 🙂


Shape the hype cycle with tech comm

You can use technical communication to accompany and even nudge technologies and products along the hype cycle.

The hype cycle

The hype cycle was invented by Gartner Research in 1995 and has since been underlying dozens of their reports. Here’s a schematic example:

image from http://newsletter.stc-carolina.org/

You can see how it tracks visibility and expectations of a technology across time in 5 stages, from the Technology Trigger up to the Peak of Inflated Expectations and down into the Trough of Disillusionment, then slowly up the Slope of Enlightenment, until it reaches the final Plateau of Productivity.

I think there a few remarkable things about the hype cycle:

  • Let’s get the obvious out of the way: It’s not a cycle at all, but a curve… 🙂
  • Different types of companies may engage in the cycle in different stages. That means the hype cycle is not some fate to be endured, but something that can shape corporate strategy – and by extension content strategy.
  • The hype cycle is not just for managers and marketeers. It speaks to our industries as well: Tech comm consultant Sarah O’Keefe started an article on “The Hidden Cost of DITA” with it in 2008 (that’s where I got the example above). And UX designer Ron George put one up on his blog last year.

Enter technical communication

So what does technical communications have to do with it?

We technical communicators provide the words around stuff on the curve. So we can put a spin on them, to a certain extent. I don’t think we can move a technology or a product into a totally different stage with documentation. But I believe we can mitigate adverse effects and nudge our subject along the curve a little.

There are two reasons why this works:

  • Technical communication is part of the hype cycle. Whether we take it into account or not, our documentation contributes to the item’s visibility, and it certainly shapes expectations on it.
  • Technical communication can be dynamic and agile. It is usually quite easy and fast to change the technical communication in contents, tone and spin to address a new use case, an additional persona or a different audience.

And there are several ways how you can use technical communication to influence the hype cycle:

  • It’s all about context. You know this already, if you’ve ever thought about personas, your audience and their situation when they are using your product. So take into account the hype cycle, especially that difficult phase into and out of the Trough of Disillusionment. “First contact” documentation such as quick starts are particularly suited to address inflated expectations and to offer a shortcut to the Plateau of Productivity.
  • Position yourself as the users’ advocate who accompanies them along the curve. Who is better suited to guide them up the Slope of Enlightenment than us technical communicators? Keep visibility of the product and its benefits up (to the limited extent that you can), and keep users’ expectations realistic.
  • Engage with the users. Hiking up a slope in silence is no fun. Find out what interests your users, what they try to do and where they want to go with the product, whether by soliciting feedback or user-generated contents. (But don’t forget to check back with your diligent product manager about the general direction…)

Your turn

What do you think? Should you, can you write with the hype cycle in mind? How can it affect the relationship between technical communications and marketing?

Top 3 success factors in online help systems

Service speed as well as content’s structure and spacing are the top 3 factors that determine whether your online help system is successful. That’s the gist when I apply 7 of Cameron Chapman’s “10 Usability Tips Based on Research Studies” to online documentation.

Cameron’s post of September 15 looks at the numbers behind the usability of web sites and, as she writes, “some might surprise you and change your outlook on your current design processes”. And they underscore the importance of offering documentation that’s quick to find, understand and apply.


Speed is essential for online help success in two ways.

Write help content so it is fast and easy to skim and understand. Cameron mentions two studies by Jakob Nielsen:

  1. Users read only about 28% of the text on a web site, and the ratio decreases with the amount of text.
  2. Users follow an F-shaped pattern when skimming web sites. They start reading at the top left corner (in cultures which read left to right, top to bottom), skim key words along the line and move down the lines in that pattern.

To optimize your online help for such behavior, you can:

  • Use headings, bullet lists and parallelism to ensure that users read the “right” 28% of the text. These are the parts which orient readers and guide them to the solution of their question, and then the solution itself (and hopefully they read more than 28% of that page…)
  • Front-load your headings, list entries and paragraphs so readers get the gist from the beginning.  This quickly guides your readers and helps them in their F-shaped survey of your contents.

Power your server so  it is fast to load and display the online help. Cameron refers to a study for the Bing search engine which shows significant decreases in clicks and user satisfaction once load times exceed two seconds. I assume that online help servers meet with similar impatience: Just like a search engine, they are intermediary services which users consult when they really want to do something else.

So measure and ensure that your online help web server can offer users short loading times. This is especially crucial in multi-step rendering processes of dynamic content which involve first a database and then on-the-fly rendering in HTML + CSS.


The spatial design of information is the second essential factor in the success of your online help.

Use white space to improve readability and reading comprehension. A study at Wichita State University found that users prefer text on web pages with margins and optimal leading (= vertical spacing between text lines). They also retain better what they have read.

“Don’t worry about ‘the fold’”, says Cameron. Contrary to popular belief, users do scroll and read below the ‘fold’ of the initially visible top part of a web page. Cameron points to studies by a web analytics company and design agency which conclude that there is no correlation between page length and the number of readers who scroll at least 90% to the bottom. Instead, users apparently scroll when they think it’s worth scrolling – which again emphasizes the content, its readability and usability.


The structure of topics and contents in your online help is the third essential factor.

Navigation beats search. Cameron cites two studies that found users prefer navigation and usually resort to search only after the navigation failed them. (I assume this differs for experienced users who know what they can expect from navigation and search respectively.)

So do your technical communications team and your users a favor and maintain a solid topic structure that writers and readers find worthwhile to use. A good topic structure is a map that orients users throughout the system and in context. By contrast, a search result merely shines a spotlight on the topic a reader may or may not need. In short: Don’t let your search bail out poor structure and bad navigation.

Related topics

Cranking widgets: “Getting Things Done” (GTD) as a tech writer

“Getting Things Done”, David Allen’s productivity method, works well for a technical writer who’s lined up tasks, so they’re ready to go and as easy as cranking widgets. Here’s how in my #2 GTD Principle for Tech Writers. (My #1 principle is about universal capture.)

Cranking widgets

Most of us technical writers face two different types of tasks: Deciding what to do – and actually doing it. It’s the second part that David Allen calls “cranking widgets”. It sounds like a mindless activity, but I take it to mean to get down to our craft and actually write. (For a more GTD-like take, try zenhabits’ recipe…)

I believe, and have experienced, that it makes sense to distinguish and to separate those two types of tasks as soon as a task appears. That gives me a slim chance that I’ll even have the time to decide before I actually have to do it.

The benefit is that I get to group similar tasks together and do related work at once, so I don’t have to jump around in the documentation with every single task I get.

The challenge is to juggle the deciding and the doing. Often I don’t have the time to do all the deciding until my inbox is empty and all tasks are neatly laid out and ready to be done.

Deciding before doing

This kind of task often comes disguised as the second type:

  • I get a phone call that asks me to correct something in existing documentation.
  • I receive an email about something that hasn’t been documented yet.
  • I get a request to furnish screenshots for a localized manual.

All these things need to be done eventually. But for efficient and effective documentation, it makes sense to first decide what to do exactly:

  • Is the correction in existing documentation actually legitimate? And if so, when is the best time to do it?
  • Is the missing documentation actually missing, or overdue from the latest release, or really part of a future release? Again, when is the best time to write and provide it?
  • What’s the most efficient way to get the screenshots for localization? Do I have to do those, or can I ask an intern to do them? If I should do them, should I change my process and create them along with the ones in the source language?

How to decide

The reason to keep the deciding apart from the doing is that the first engages me in a very different way. Deciding what to do is mainly thinking, planning and organizing: Is a request legitimate and timely? What do I need to do that? When is the best time to do it? This part is mainly concerned with logistics.

My answer is usually one of those four decisions:

  1. Do it now. This is what I choose for tasks that simply cannot wait and for tasks which don’t take very long. In other words, tasks which get much bigger by looking and deciding a couple of times. The risk is that these tasks take up much of my daily time, but the reward is that they’re in and out fairly quickly.
  2. Defer it to a set deadline. This goes for all requests that come with a deadline, whether it’s explicit or implied, for example, because it’s connected to an upcoming version or release of the documentation. These tasks go onto my to-do-list. You can also put them into your calendar or project plan…
  3. Defer it to sometime later. This is for everything that’s currently out of scope or merely nice to have. It goes on to a wish list.
  4. Delegate it. This is frequently wishful thinking, because most of the time I don’t have anyone to delegate to… 🙂 But occasionally, I get lucky and can ask an intern to take those screenshots… After I delegate the task, I’ll have to make sure to follow up, especially when it’s got a deadline.

Doing after deciding

Once I have sorted out (hopefully most of) my tasks, I can set about doing them, starting with the most urgent ones, but taking all the related ones together. I’m cranking widgets and, if I’m lucky, I might get into the flow.

Your turn

Does arranging your tasks work for you? Or do you have your work arranged for you? Or do you simply not have the time to even bother? Feel free to leave a comment.

Psychology & technical communication, Chris Atherton at TCUK

Technical communication benefits greatly from cross-pollination with related disciplines, such as cognitive psychology. That was my conclusion after the presentation “Everything you always wanted to know about psychology and technical communication … but were afraid to ask” by Chris Atherton (@finiteattention).

Chris is an applied cognitive psychologist and Senior Lecturer at the University of Central Lancashire. She has the rare ability to cut through the crap without shortchanging her subject or her audience. She makes Occam’s razor user-friendly, if you will.

Here are my top 3 insights from Chris’ presentation and how I find them applicable to technical communications:

1. Do your reader a favor and supply context

Context relates different pieces of contents. More specifically, it relates what users already know to what they need to learn right now as they read the help. For example, an essential setup procedure is not helping the user, if they don’t know where to set up stuff. Well-written headings and carefully arranged “related links” help users to establish context and to evaluate whether the content they found is relevant to them.

Context also means the “location” of pieces of content. That location can be in a book (for example, about half-way through), on a page or screen (near the top) or in an online table of contents, such as Word’s document map (a sub-topic on one of the first branches after the introduction). Note that all the examples are really vague. But as Chris says, “we remember the gist and location.” And that’s what we go by when we try to find content again.

By the way, Chris pointed to research by Jakob Nielsen who found that location still works on long pages that require vertical scrolling! Apparently, readers do scroll – and remember the general location of what they read.

(You might recognize these points about context as two of my Top 10 things that users want to do in a help system.)

2. Simultaneity implies causality

That means that we often understand two things happening at the same time to be related by cause and effect. In technical communications, this is most relevant to training videos and user interfaces. For example, two call-outs appearing at once will be assumed to be related somehow. Don’t let the user guess, instead:

  • Be careful to create logical sequences.
  • Avoid presenting alternatives or unrelated items at the same time – and if you do, ensure to label them clearly (which will hopefully clutter up your screen or script enough to convince you to break them apart…).

Another example where simultaneity implies causality is people who can turn off streetlights simply by walking past them – which brings us to:

3. Don’t waste time catering to dogmas

This is a tricky one: Some psychological concepts are generally accepted as facts. Yet they make many scientists gringe, because the numbers and the evidence just aren’t there. For example, Chris referred to substantial criticism that’s hacking away at the alleged foundations of individually preferred learning styles.

For me, as a non-scientist, that means that I can support different learning styles in my documentation if it’s done easily and with no or insignificant additional effort, but I won’t go out of my way.

From here on, it’s a sliding scale into the murky depths of psychobabble which is easier to decode and ridicule. To quote an example from an NLP website: “Use brain gym to calm, energise or reconnect right and left brain for improved concentration.” (Apparently, in most people, the left and right brain are successfully connected, regardless of the brain trouble they may believe to have…)

Your turn

Do you know of other insights from psychology that can benefit technical communications? Or do you want to share ideas or experiences with one of the ideas above? Feel free to leave a comment!