Overview

Use the following rules when creating content for Help articles. Refer to the General Writing Standards section for help with specific topics.

Refer to the sections below for some guidelines around writing instructions.

Although technical text should be sparsely written (direct and to the point), it is best to provide some variety and flow, even in the non-conceptual, step-by-step instructions. For example, four or five steps in a row beginning with the work 'Click' can be monotonous for the reader. This can be remedied by providing minor variations in the working to improve the flow.

General rules to bear in mind are:

  • Ensure appropriate sentence length is maintained. Avoid overlong sentence structures.
  • Write in the imperative (that is, using commands) for numbered, step-by-step instructions
  • Concepts (solutions without steps that are more explanatory) can have a slightly less clinical tone and do not always have to be in the imperative. However, the language should still be concise.
  • Unless you are giving a scenario by way of example (in which case, you would use the conditional tense), write instructions in the present tense, for example: In the top-left of the screen, there are two indicator squares. (Rather than: In the top-left of the screen there will be two indicator squares.)

When an instruction such as 'Click OK' or 'Click Next' relates to the instruction provided directly before it, combine the instructions into one numbered step, for example:

Enter the SDS name in the field provided then click OK.