Why projects need task-based documentation

Off the Beat: Bruce Byfield's Blog

Jan 30, 2015 GMT
Bruce Byfield

Documentation in free software has improved immensely in the last fifteen years, At least most projects have some, which is more than could be said when I first started using Linux. However, far too much of it stops with descriptions of menus and dialogue windows instead of being structured by tasks and user.

The type of documentation you find in perhaps two-thirds of the most popular applications is what I like to call death marches through the menus. Like some forced march of prisoners, a death march starts resolutely with the first item in the File menu and tramps relentlessly down and up each menu in turn until it reaches the last item at the bottom of the Help Menu. Each menu is given a sentence or two of description, and rarely so much as an example. If you are lucky, a death march might also include pictures an application's main menu or even the dialogue windows, although you can never count on such luxuries. By their nature, death marches are not designed to be read from beginning to end, and any attempt to do so can make you feel that you have just shuffled kilometres over barren sands, half-dead of thirst and shackled to bullying convicts.

By contrast, task-based documentation is broken down into the activities that users will go through as they work. These activities begin with the first tasks that users are likely to, and continue onwards with those that become possible as users continue to work. Typically, advanced or occasional tasks appear at the end. The very best of task-documentation will also anticipate the choices users face at every stage, and suggest the considerations that might go into making a decision.

Without such anticipation, task-based documentation is still more useful than a death march, but is weakened by a loss of context. Still, in my rough and rather random estimate, perhaps a quarter of documentation is task-based with minimal context.

Reasons for the death march
Task-based documentation with context has been proved again and again more effective than death marches. Yet if a project chooses only one, it almost always opts for a death march. Why?

One reason is that death marches do have a legitimate use in mouseover help. You can write the mouseovers for individual widgets, then present much the same material as one long document or series of hyperlinks as online help. In this sense, death marches may appear more efficient.

Another reason is that developers are most familiar with man and info files -- reference works that few read from beginning to end any more than they would read a dictionary. The most a man page is likely to do is to give a few examples at the end. As a result, their idea of documentation often barely contains even the concept of task-based documentation.

However, the main reason for death marches is how documentation is written. In both commercial and community-built software, documentation typically comes at the end of the release. Often, documentation is so much of an afterthought that it is written after the software is released. The times when it is not, the writers are often pulling all-nighters to finish before the release, because while developers are sometimes willing to delay for technical reasons, many do not consider documentation worth a delay.

Under such circumstances, death marches are easier and quicker to write. Moreover, to those who are never going to give them more than a superficial look, they look just as good as task-based documentation -- certainly better than being press-ganged themselves when they are tired at the end of a hectic development cycle.

By contrast, task-based documentation is more demanding. Even when it fails to give adequate context, it requires a thorough understanding of the software and how to use. It also requires either user testing -- which is still a rarity in free software projects -- or else the imaginative ability to anticipate how an ordinary user might approach the software, a skill that few people can be reasonably expected to have.

Usually, too, task-based documentation requires access to the software as early as possible in the development cycle. Giving writers such access is not impossible, but it does require reorganizing the process somewhat.

Even more importantly, task-based documentation requires the ability to write clearly, concisely, and precisely. Not only are these abilities rare, but people who can both write clearly and handle technical matters are even rarer. Developers often lack the writing skills, which makes their efforts at documentation incomprehensible, while writers lack the ability or willingness to learn technical matters, which makes their efforts superficial and next to useless.

Fitting documentation into development
Too often, writers are not part of the development team, or else so incompetent technically that developers disrespect them. Some developers, too, can be impatient when writers interrupt them with a request for explanations.

Still, if a project wants first-rate documentation, getting writers involved early and giving them time to write is essential. However, such efforts pay off, and not just in making life easier for the average user: If you can find people who can both understand technical matters and express it, you can justify their involvement by making them first users or testers as well.

Yet however you organize, a task and context-based orientation is essential if you care about having the best possible documentation. Without it, your documentation will be quicker to write, but you are almost sure to waste the time of both yourself and your users.

comments powered by Disqus
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters

Support Our Work

Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.

Learn More