The manual: possibly the most awkward part of a user’s experience with a product. People avoid manuals whenever possible and designers try to build interfaces that need not rely on them. And yet, users and designers would certainly agree that you simply must provide a proper manual.

The manual can be a powerful tool for unleashing the full potential of an application, something of benefit to users and vendors. Why is it, then, that manuals so often seem to confuse users rather than help them?

Let’s look at the most common difficulties faced by technical writers, and how to best deal with them to improve the user experience of manuals.

The Style: Book vs. Booklet

Before even touching the content of the manual, stylistic attributes can be decisive in convincing users to pick up and read the manual rather than trying to figure out the interface on their own (and calling customer service if they can’t).

If the manual remotely resembles a telephone book in size, chances are that users won’t bother reading it. Still, you shouldn’t sacrifice content for brevity. Manuals have to be comprehensive for a reason. If users accidentally click on a button that triggers a possibly dangerous process that is not covered in your manual, questions of security and liability will arise.

If you feel that the functionality of the product requires a very big manual, it’s worth providing a quick start guide along with it. Give users a general map of the interface and explain its basic functions so they can explore without a risk of breaking things.

Something that will add pages to your manual is white space. There is value in line-spacing in between paragraphs or as margins. Used properly, white space can increase both reading performance and comprehension, but be careful not use too much of it.

Consider the fonts, too. A common practice is to use serif font types for print, and sans-serif fonts for online body text, but when it comes to font types and sizes, personal preferences simply vary. Know what has worked well in the past and be open to experimenting. Most importantly, test your choices with users.

The Table of Contents: Logical vs. Consistent

Technical writers usually recommend structuring the table of contents in a clear hierarchical manner. Good advice, but it requires a little more elaboration.

The table of contents in the manual and in the product interface need to maintain a complementary information architecture. The manual structures the functionality thematically while the interface structures it visually. If the thematic structure of the table of contents is not consistent with the visual structure of the interface, it can confuse users.

For example, in versions of Microsoft Word prior to 2007, in order to add a header or footer, you had to go to the View menu and check the Header or Footer entries to format the page accordingly. Headers and footers were treated by the interface as a formative part of a page. With the introduction of the Ribbon Interface in 2007, this changed slightly. In order to add a header or footer in Word 2007 and later, the standard way is to click on the Insert tab within the Ribbon and then the Header or Footer icon.

Headers and footers are now treated as external items and grouped in the same tab with other external items, like pictures, charts, tables, and symbols, that are typically viewed as additional (not formative) elements of a page.

The question is how and whether to reflect this change in the table of contents. Logically, it would seem perfectly fine to set up a chapter called “Formatting the Page” with subsections for Headers and Footers, and a chapter called “Inserting Items” with the subsections Pictures, Charts, and Tables. This, however, would contradict the visual structure of the interface at hand.

It would be better to include subsections in the chapter “Inserting Items” that accurately correspond to the interface, namely Pages, Tables, Illustrations, Links, Headers and Footers, Text, Symbols, etc… This would avoid confusion and strengthen the users ability to create a mental map of where to access a certain kind of functionality.

The Instructions: Goal-oriented vs. Descriptive

Usually, the idea behind instruction manuals is to present a specific goal to the users guide them, step by step, toward it. While this approach works well for some workflows or even entire applications, sometimes a more descriptive approach may be more appropriate when goals are less clearly defined.

For example, the classic case of a goal-oriented workflow is the installation process. The goal, installing the application successfully, is clearly defined, and there is likely very little deviation along the way. The interfaces of many installation wizards are indeed designed to take you through a fixed, chronological sequence of steps.

Goal-oriented workflows are often communicated by the application itself with success messages like “installation successful” or “transfer complete.” Other workflows are best for products and services with goals that are not as clearly defined, like productivity applications.

Users working with productivity applications often have the goal of creating great looking documents, videos, presentations, etc, which is a fuzzier concept to break down. Using smaller sub-goals won’t help very much either. When writing a manual for a productivity application, you will have to teach users about the different functionalities the program provides and how to easily control them.

Take, for example, the color picker in Photoshop.

The interface itself does not communicate any particular goal other than the ability to manipulate the color properties of the selected area in one way or the other. You will have to break down or chunk the interface element at hand into areas that represent different types of functionality and sub-functionality. In the case of the color picker above, you would have to explain what the color field to the left represents and how it relates to the color slider in the middle. The color notation or color values (Hue, Saturation, RGB, CYMK, etc …) to the right also need to be explained.

In situations where a goal is pretty much up to the users to define, a more descriptive instructional method will allow them to better find their way around in the application and experiment with all the available tools and settings until they achieve a result they are happy with.

The Language: Technical vs. Colloquial

Technical writers often suggest using simple language devoid of technical jargon that users may not be familiar with. Very good advice, but a couple of things should be considered.

Often, the interface itself may use a very technical language. In this situation, in order to maintain consistency, the best thing you can do is to explain the technical terms in a glossary. Although cross-referencing can become tedious to users, this is usually the most acceptable solution. It's not to hard to navigate a glossary and the alternative—explaining the technical terms wherever they fall in the text—can easily clutter your instructions and simply get in the way if users happen to be familiar with the term or concept.

Using a language that is too casual can also work against you. Some technical writers, such as David Pogue, use a rather conversational style, and while it’s not impossible to be both entertaining and instructive, be aware of the risks involved.

Being entertaining is great, but users will probably want to read your manual to simply get their work done as quickly and efficiently as possible. They will have to follow sequences of commands and results, a fundamental principle of human-computer interaction that holds true irrespective of the instructional method you choose.

Anything that goes beyond teaching users in these easy-to-understand sequences of commands and results entails the risk of distracting them, especially if your remarks are quite entertaining. With everything you write, entertaining or not, try to always keep it closely related to either the command or result you are trying to explain. This will ensure that your writing is engrossing and efficient.

The Structure: Uniform vs. Segmented

A novel is supposed to be read from the first line straight through to the last. A manual, by contrast, should allow users to quickly find what they want while skipping past undesired information. If your manual is consistently divided into meaningful segments, it can increase user comprehension while making it easier to skip unwanted information.

Headers are necessarily short and may not always give users enough of a clue as to whether a chapter or section contains information they are looking for. It makes sense, then, to always include a short summary of a couple of lines at the beginning of a chapter or section, preferably indicated with a bold “Summary:”. This way, users will not have to read the entire chapter. This is also a good place to make users aware of possible dangers attached to certain functions or how they relate to other functions.

You can also use the principle of meaningful consistency to further structure and refine the instructions. For example, always put commands and results in separate sentences. Always make commands, and only commands, bold. Always indent your instructions. Always use bulleted lists for options and numbered lists for chronologically fixed steps. Always place pictures beneath the respective instruction, never above.

Lastly, consider your appendices. Sections such as indices, FAQs, troubleshooting sections, and glossaries are popular among users because they have a familiar and consistent structure (Q&A, alphabetical, error & solution, etc.), which makes them easy to scan and to navigate. Interestingly enough, this is the one area where you should deliberately deviate from the principle of maintaining consistency with your interface. Instead, work with the users to find the keywords, synonyms, and questions they are most likely to look up first.

Final Thoughts

User manuals play a crucial role in user experience—not just with the manual itself, but also with the product. Unfortunately, manuals are often a source of frustration rather than assistance. Every application is different and requires a different approach. Although there are many useful tips for technical writers, the difficulty is to knowing which advice to follow and when to follow it.

Technical writers need to be involved in the development of an application right from the outset, so that they truly understand how it works. This will yield better results than handing them a finished product and a deadline. Only then will they be able to use their analytic and linguistic skills to simplify these processes for the users and turn the manual into the powerful tool it was always meant to be.


Image of garden labyrinth courtesy Shutterstock


Hi Andy and thanks for your comment,

You are right that users will always have to follow some kind of procedures, or sequences of commands and results, as I called it, whether it is to install an application or to paint with a brush. And those procedures should also always happen within a proper context, which you could explain at the very beginning of a chapter.

However, bear in mind that different applications serve different purposes, and ideally, this should also be reflected in your instructions.

When goals are more or less up to the users to define, as it is the case with great looking documents and productivity applications, then users should feel encouraged to experiment with the available tools until they are happy with the result. In order to give them this confidence, you will have to put more emphasis on the descriptions, not so much on the procedures.

Take, for example, your own procedural topic “Setting up a custom canvas color”. The procedure to set a custom color is rather short as users would merely have to bring up the color picker, choose a color and confirm their selection. However, the descriptions and the conceptual information about color fields and color sliders, color models and HTML notations and how the users can control and experiment with them is actually longer and also what makes the application interesting and gives users the confidence to explore and experiment with it.

Now, by contrast, consider a disc burning application. The goal is to transfer a set of files onto an optical medium in a way that renders them playable on the target device. This goal, however, is not defined by the user as much as it is defined by Sony, Toshiba, Panasonic, etc … In order for your disc to be playable on the target device it will have to fulfill certain specifications. In this case, experimenting too much could rather lead to frustration and wasted CDs.

So instead, as both the application and you as a technical writer know best what works well on the target device in terms of compatibility and quality, emphasize the procedure that will produce the right disc type and spare users from trial-and-error. And while I am sure that there are many interesting conceptual things to know about ISO-standards, codec algorithms and the NTSC/PAL dichotomy, in this case, I would recommend to keep the explanations to a minimum.

One thing that can, of course, mess with the above-stated binary is if the application is not properly designed. If controlling the functionality in a productivity application, an essential task, requires long, complicated procedures, then, as Sarah Maddox correctly pointed out, there is likely a problem with the UI and you as a technical writer could point this out to the developers.

You are right that my article is rather basic but you should not therefore dismiss the above-stated binary so easily. I would say that it is a useful and accurate guideline to allow technical writers to balance procedural and conceptual information. Hope this helps.

Great write up of some of the basic considerations to keep in mind when planning user assistance deliverables, Anastasios!

I do think that you introduce a bit of a false binary when discussing "The Instructions: Goal-oriented vs. Descriptive" when there is always a place for both in well crafted technical writing. Goal oriented (or task oriented) procedures are key to helping users perform the tasks they need to perform to reach their goals, while descriptive information provides context and detailed options that can be considered while performing those tasks.

In your example of a color picker, I can see having a procedural help topic for "Setting a Custom Canvas Color" that would outline the steps that user needs to take to perform that task. That task would be much easier for a novice user if there was an additional topic along the lines of "Color Picker Overview" or "Understanding the Color Picker".

I love of these tips can be applied to online user manuals as well, good stuff.

Many (most?) products that are web-based offer only online user manuals, and I've noticed that many of these companies have cross-functional people on their team create the user manuals rather than technical writers. I made a free template for these individuals, and I'm going to have to incorporate your ideas into it:

Hallo Anastasios

Thanks for an interesting read! I'm a technical writer, and I can certainly identify with the quandaries that you've described. We're continually re-evaluating and re-designing our documentation to suit our audiences and the company goals. That's an important part of the job.

In reply to the last paragraph, I'd say, 'Yes!' And more: If we involve tech writers from the outset, tech writers can contribute to the design of the UI. Being the people who explain to users how to perform a certain task, tech writers gain an advanced knowledge of processes and of how people go about doing things. If a tech writer sees that she will have to write a long and convoluted document explaining how to do something, there's probably an issue with the UI. By adjusting the UI design up front, we can reduce the requirement for documentation and improve the customers' experience.


Hi and thanks for your comment,

of course you can translate it.

Thanks for the article. May I have permission to translate your article into Korean and use it on my blog?

Very well written. I recently was in the throes of writing technical manuals for BI Tool for a multi-national marketing agency. While I became intimately familiar with the product itself, there were some hurdles. It was a tough slog, in part because of the cross-section of end-users across varying levels of technical capability, as well as the diverse industry jargon in the various departments and silos. Many terms were NOT mutually exclusive - especially considering the global distribution of the manuals.

Thanks for the read.