Technical Documentation Know-How

Many people in charge believe that writing technical documentation doesn’t require any special qualifications.

From the technical point of view, this is true. Appropriate authoring software generates neat user manuals and online help files with a click of a button.

The didactical side, however, is much more challenging. It’s no coincidence that so many people hate reading manuals and thus fail to use even simple products. This happens when a manual doesn’t reflect how users think, and when a manual presumes prior knowledge that users don’t have.

The know-how of writing plain user assistance that every user can understand is the ability to bridge the gap between the users’ prior knowledge and the knowledge required to use the product. User assistance shouldn’t challenge the reader. Instead, it should build up confidence, motivate the user to explore the product, and guide the user along the shortest way possible.

> Play intro (80 seconds)

When planning to create new user manuals or online help files, or when reviewing existing technical documentation, you may find the following checklists useful:

▪Documentation Quality Checklist
Helps you to identify potential weaknesses of existing user manuals and online help files. You can also use the listed criteria to evaluate your own work while writing.

▪Choosing a Help Authoring Tool
Describes what to consider when looking for a suitable authoring tool to create technical documentation, especially software user assistance such as printed user manuals and online help files.

▪Choosing a Screen Capture Tool
Describes what to pay attention to when looking for special software to take and edit screen captures (screen dumps, screenshots).

▪Choosing a Screencasting Tool
Lists the key criteria that are important when selecting a tool to create interactive software demos (screencasts).

To help you find suitable authoring tools, we’ve compiled a number of market overviews of useful software. The lists include tools to create and edit user manuals, online help files, and screencasts, as well as a number of other working aids for technical writers and translators.

Additionally, we’ve included a number of lists of useful web sites and recommended books. This is a collection of the resources that we use ourselves in our daily work as technical writers.

You can find the links within the navigation area on the left.

We’ll also be happy to provide individual advice and to design, write, or improve user manuals, online help files, and screencasts for you.