Technical Writers’ Companion

▪If the task is so complex that you can’t describe it within one topic, just outline the major steps and link to other topics that each contain the description of one subtask.

▪Don’t explain why things are done in a particular way.

If you need to provide extensive background information, link to a Concept topic (siehe Writing “Concept” topics). However, it’s OK to include a short conceptual element if this explanation helps users to avoid mistakes or if it helps users to better remember the steps of the procedure.

▪If the procedure involves any hazards, add a warning immediately before the step that involves the hazard (siehe Writing warnings).

▪It’s not the job of a Task topic to provide technical data or detailed reference information.

If required, link to a Reference topic (siehe Writing “Reference” topics). However, it’s OK to give a short list of parameters or brief explanations of options if setting these parameters must be done by all users who perform the procedure. To also make this information accessible to advanced users who don’t read the Task topic, add the same information to a Reference topic as well—even if this means redundant information (siehe Structuring: Find the right amount of redundancy#).

▪Describe only one way to accomplish a goal. Choose the most common and easiest way. When documenting software, describe keyboard shortcuts in a separate reference of shortcuts.

According to the principles of structuring content, each topic should be self-contained (siehe Structuring: Make topics self-contained).

Depending on how you write the heading, you can design a Task topic to contain a family of procedures or a single procedure.

The advantages of single-procedure Task topics are:

▪The topics are shorter.

▪Users can access each procedure directly.

The advantages of multiple-procedure Task topics are:

▪Procedures stand in a broader context, which often helps to explain their use and relationships.

▪Related procedures are obvious and don’t have to be linked to.

▪Clustering closely related procedures reduces the total number of topics.

▪Having fewer topics makes navigation easier (readers must scan fewer entries in the table of contents; there are fewer links to related topics).

Example of a single-procedure Task:

topic title: Deleting Files

Example of a multiple-procedure Task:

topic title: Handling Files
first subsection: Creating Files
second subsection: Editing Files
third subsection: Deleting Files