Technical Writers’ Companion

Regardless of which structure model you choose:

▪Begin with the most important information, and end with the least important information.

▪Put the information that all readers need before the information that only a few readers need.

▪Put basic knowledge before expert knowledge.

▪Put what’s easy before what’s more difficult. (This is especially important for tutorials and getting started sections, where you should motivate users by giving them a sense of achievement as soon as possible.)

▪Put things that happen often before things that happen rarely.

▪Put general information before more specific information.

▪Put concepts before tasks, and put tasks before reference information.

▪Put what’s required before what’s optional.

▪Keep related information as close together as possible.

When possible, provide 1-click access to frequently needed information. Put that information on a high hierarchy level that’s:

▪important

▪needed frequently

▪needed by many readers

Example:

If you expect that many users will use keyboard shortcuts, don’t create a hierarchy like “Appendix > Expert Features > Keyboard Shortcuts” but include the topic “Keyboard Shortcuts” on the top level.

A user-based structure can reflect:

▪user groups

▪the expertise of users

▪use cases or scenarios

▪stages of use

▪users’ goals

▪users’ tasks

Tip:
User-based structures make documents user-friendly because they directly take into account the users’ needs. For this reason, when you can apply a user-based structure, do so. Apply user-based structures in particular to procedures.

Often, you can find major goals that comprise a number of tasks. Try to find verbs and then put them into a hierarchical structure.

Example:

▪creating, changing, and deleting can be grouped into managing

▪displaying, printing, and exporting can be grouped into outputting

A time based structure can reflect:

▪the chronological order of things that are done by the product

▪the chronological order of processes that happen within the product

▪the chronological order of steps that users must perform

Tip:
Use a time-based structure in particular for procedures and process descriptions.

A product-based structure can reflect:

▪components or modules of a product

▪operator controls on a device

▪the menu structure of a program

You can arrange items:

▪from left to right

▪from top to bottom

▪from the outside to the inside

▪from big to small

Many writers use a product-based structure because the product-based structure is already “given” by the product, so it’s easy to set up without much consideration.

Many readers, however, dislike product-based structures because they don’t reflect what readers are looking for within the documentation.

Tip:
Use a product-based structure for reference information, but don’t use it for concepts, procedures, and examples.

Many subjects lend themselves to natural division. For example, the world can be divided into continents, continents can be divided into countries, countries into districts, and so on.

A topical structure can guide the reader to the correct topic only if the reader already knows and understands the basic principle behind the structure. So topical structures require at least some basic, prior knowledge of the subject.

Within the main chapters of a topical structure, you often need a second criterion to organize the subchapters. In the example of the world, for instance, you could sort the continents, countries, and districts either alphabetically, by size, or by number of inhabitants.

Alphabetical and numerical structures:

▪have no logical and no didactic approach whatsoever, so they’re inappropriate for conceptual information

▪enable readers to find specific information quickly; however, finding information only works if readers already know the subject well enough to be able to look for the right terms

▪only make sense when there’s a large number of items

Tip:
Use alphabetical or numerical structures for reference sections when there’s no other, more obvious structure. Also use alphabetical or numerical structures when you expect that most users will use a document or document section primarily like an encyclopedia.