Design for your audience
Don’t create a design that designers would like. Create a design that meets the needs of your audience.
Examples of requirements resulting from the audience are:
Examples of requirements resulting from where and how the audience reads your user manuals are:
Keep the design clear and simple
Less is more. Keep the design of your user manual template as plain and simple as possible. Don’t distract the reader. Create a design that helps the reader to retrieve and process the given information.
Avoid unnecessary variety
Avoid redundancy
Omit every letter, symbol, line, or other object that doesn’t add any real value.
For example:
Tip: Sometimes, the design guidelines of a company inevitably require having particular elements on each page, no matter whether this makes any sense. If, in a case like this, you can’t influence the design guidelines (you should try), at least keep these elements as unobtrusive as possible: make them small, don’t use color, make text light gray instead of black, place the elements where they draw little attention and clearly separate them from the true content.
Avoid clutter
Don’t overload the pages of your user manuals and user guides with too much information. Use white space purposefully to direct the readers’ attention, to group things that belong together, and to set reading pauses.
It’s no problem if an uncluttered layout makes your user guides a bit longer. If you provide valuable content, readers will accept the fact that they need to scroll or turn pages. However, they won’t accept user guides that overwhelm them.
Create styles semantically
Use style names that describe the meaning of a style, not its look. For example, call a style “Emphasis” rather than “Bold-Red.”
Semantic styles have some major advantages:
Use a well thought out naming convention
To make your user manual template writer-friendly, set up an effective naming convention for style names:
When writing, avoid amateurish formatting techniques
Don’t use …
Only use the styles that are configured in your user manual template.
Problems with empty paragraphs
Don’t use empty paragraphs for adjusting the space above or the space below paragraphs. Instead, use appropriate paragraph settings.
Also, don’t use empty paragraphs for creating page breaks. If you later add or delete some lines from your user manual, everything will move to a wrong position. Instead, always use proper manual page breaks. Even better, when possible completely automate page breaks.
All sorts of empty paragraphs seriously interfere with automatic page breaks.
Problems with multiple space characters
Don’t use space characters for indenting text. Instead, always configure proper indentation settings as part of the paragraph properties. If you use space characters for indenting text, as soon as you change anything, all subsequent lines also need manual editing.
In online user manuals that use a variable column width, indents with space characters don’t work at all.
The only place where using space characters for formatting text within a user manual makes sense, is when quoting programming source code. When you copy and paste source code into a user manual, the source code is usually already indented with the help of space characters or tabs.
Problems with tabs
Avoid using the tab key. Tabs may get you into trouble if you want to produce an online version of your user guide because tabs don’t have any equivalent in HTML. Tabs then need to be converted into tables, space characters, or indents. This rarely works well.
Instead of using tabs, set up some proper paragraph indentation, or use a borderless table. Note that even if you don’t need to produce an online version of a user guide now, you may want to do so in the future.
Problems with local custom formatting
Don’t manually set paragraph settings and character settings for individual paragraphs. Always only use the paragraph styles and character styles that have been defined in your user manual template. If you overwrite a paragraph style for an individual paragraph or if you overwrite a character style for an individual word, this will get you into trouble when you need to change the design of your user manuals. This may seem unlikely today but often happens even if you don’t anticipate it.
If you have exclusively used template styles and want to change the design, all you need to do is to change the style definitions. If you’ve applied manual formatting, however, you will need to update all manual formatting by hand. This can result in many hours of extra work, particularly if you have multiple documents.