Identify your requirements

Identify your objectives. What is the reason for the document? What key messages are you trying to relate? Boil down your intent to as few key messages as possible.

Are you trying to inform the readers about something, or are you trying to get them to do something? Usually a given segment of text should do one or the other, and not both.

Identify your audience. To whom are you trying to communicate your key messages? Knowing the target audience is essential to identify your audience's objectives. What is your audience interested in doing? To keep your readers’ interest, find a way to link your subject to something that satisfies their needs.

Break up the area of discussion into focused topics

Strive to keep the objectives for a given document as narrow as possible, to keep the text concise and focused. Choose specific objectives; decide if you are informing your readers or trying to get them to act; identify the goals of your audience.

Break down your topic into specific segments, each with a distinct purpose and covering a specific aspect of your topic. Avoid discussing one aspect in multiple places, from the viewpoint of the objectives for this document (a document with different objectives may breakdown the document in a different way).

Bear your readers’ objectives in mind

When feasible, write the text from the point of view of your readers and the questions they have. Try to address their most important concerns based on their objectives. This helps keep your readers engaged.

When editing existing text, keep each portion cohesive

Ensure that each edit you make to a document maintains the cohesiveness of each segment of text.

Integrate your changes into the existing documents

Often you are tempted to dump a new piece of information anywhere within the existing documentation, figuring that someone else will eventually integrate it into the rest of the document. Unfortunately, this can quickly reduce the cohesiveness of a document, or lead to documentation that repeats information in many different places.

Review the existing documents and find the most appropriate section for your changes. Reorganize the documentation as required to ensure each section has a distinct purpose.

Use signposts to guide readers through a document

A long stretch of paragraphs with a similar typographical appearance can make it harder for readers to keep track of where they are, to quickly find a section of text that they read before, and to remember the purpose of the current portion of text. Various techniques can help provide guidance:

Provide an overview. An overview, such as a table of contents or a high-level description helps readers keep track of where each portion of text fits into the overall subject.

Use section headings. This is the most common technique and allows the table of contents to serve as a list of key signposts in the document. However, as keeping tracking of many nesting levels can be tricky, particularly due to the lack of automatic section numbering in widely-available web browsers, this technique has limitations with the current generation of web browsers.

Use inline headings. Start a paragraph with a highlighted sentence that describes the purpose for the current segment of text.

Make key phrases bold. This is a variant of using inline headings and is one of the techniques for making a document easier to skim. For some type of text, such as information hubs, this technique can be used effectively throughout the text to highlight the most important keywords and steps. For text that must be read at length, such as explanatory text, the technique should be used sparingly, only to provide navigational guidance to readers looking for a particular segment of text.

Use lists where appropriate. Note lists are for enumerating a sequence of items with a certain degree of coupling. Overusing lists is common and can lead to many nested levels of lists, so where possible, use a sequence of paragraphs instead, along with one of the other signpost techniques.

Identify the text genre: information hub or explanatory text

Information hubs

An information hub consists mainly of pointers to other documents with additional information. Information hubs may contain some content as well, but typically this content will be skimmed by readers instead of read closely. Thus information hubs must be designed to be easily skimmed:

  • Highlight key words and phrases. Emphasize them by using bold or italics.
  • Group links into categories so readers can first locate an appropriate category, then a specific link within it. Even if the category is not explicitly stated, readers will be able to infer from the neighbouring links if they should continue to search that grouping for the desired information.
  • Make links easy to browse through: typically this means putting them in list.

Explanatory text

Explanatory text consists of content that that the reader must read in detail, such as a step-by-step procedure, or a detailed explanation of how a capability works. Due to the degree of attention that the reader must devote to properly understand the subject, it cannot be skimmed to learn the essential details. After having read the text thoroughly, however, readers need to be able to refer quickly to the specific section related to their current topic of interest:

  • Use a signpost in each segment of text to prompt readers of the purpose of the segment.
  • Keep each segment cohesive so readers can more easily find the information they are looking for.