Home >

Writing rules: Procedures

Writing procedures

Detailed descriptions of the functions and dialog boxes offered by any given product are always reference information, and will only be provided in the product’s reference manual and online help. A dedicated chapter is used to provide this information; Functions and dialog boxes.

Topics

Related topics

Microsoft style guide

In technical writing, procedures is a series of steps that a user takes to complete a specific task. Procedures are set off from the main text by their formatting. [...] If you document only one method for performing a procedure, document the preferred method, the method that best reflects the needs of the user.
— Microsoft Style Guide, page 99

Architecture and reuse

All procedures are written according to a fixed structure. The information modules are identified with informal headings (bridgeheads).

In XML DocBook , each procedure must be provided as a separate procedure. Information modules may be linked in from concept descriptions and/or reference information if required. Common steps may be saved as separate files for reuse. You may find it useful to omit the procedure title. Each procedure can then be placed in a separate section, and this section will hold the procedure title and the accompanying section ID as local entities in your XML document. That allows you - if necessary - to include essential procedures more than one time in a big book.

In XML DITA, each procedure must be provided as a separate DITA task topic. Information modules may be linked in from concept descriptions and/or reference information if required. Common steps may be retrieved from a dedicated repository file.

In plain HTML, each procedure must be provided as a separate document.

Microsoft Word does not provide adequate functionality to offer reuse. It is therefore strongly adviced not to use Word – or similar office text editors – to write procedures.

Procedure titles

You must always use a descriptive title for your procedure. Create a title that the reader can recognise and relate to.

  • Find titles and names that the reader would use and understand.
  • Do not use specific function names from menus and dialog boxes unless these are a part of the reader’s everyday language.
  • Do not use product names and specific item names in the title unless these are defined as variables.
  • Use the gerund form in the title.

Examples of an accepted title

Setting the date

Writing procedures and instructions

Do not use

How to set the date

Structure

Purpose

This is a very short description – typically one or two sentences – that describes the purpose of the procedure. Try not to repeat the information provided in the procedure title.

Use a dedicated informal heading “Purpose”.

Description (If applicable)

This is concept or reference information that are useful to the reader before he or she starts the first task.

It is important that you distinguish tasks from features. Limit the description to as few sentences as possible. Do not offer long explanations here, only key information. Use the related topics to refer to concept descriptions or reference information is available and/or required.

Use a dedicated informal heading “Description”.

Prerequisites (If applicable)

Identify what the reader needs before he or she can do the tasks. Do not list the obvious tools, but consider everything that may be relevant. Remember that prerequisites may not necessarily be tools and materials, it may also be a specific product configuration(s), an operational mode etc. Use a dedicated informal heading “Prerequisites”.

Highlight potential hazards (If applicable)

Use admonitions if necessary to identify real potential risks or important information.

Related topics (If applicable)

Link to other procedures, description, functions and/or dialog boxes. Use a dedicated informal heading “Related procedure”.

In DITA, the related topics are located after the procedure steps.

Procedure

Use an informal heading “Procedure” before the first task.

Steps

  • Use a numbered list. If a sub-procedure is required within a step, use alphanumerical characters to identify each step.

  • Use any number of steps required to explain the tasks at hand. The golden rule says “7 steps +/- 2”, but you are permitted to be sensible.

  • Keep the sentences short and to the point.

  • Use meaningful verbs. Use clear, present tense imperatives.

    Examples of accepted steps

    Set the starting time.

    Click Save As

  • Do not provide multiple options for doing the same task. Avoid the word “should”.

  • If you need to add additional information or explanation to a step, make sure that you clearly distinguish between the task and the additional information. Always provide the extra information in a separate paragraph from the task. You can also refer to additional information, but don’t overdo it.

  • Use examples whenever applicable.

  • Use graphics when applicable to identify buttons, icons and other visual entities. Do not include complete dialog graphics. If you need to include dialog graphics, only use the relevant part of the dialog.

  • If a command name or dialog box option ends with a colon or ellipsis, do not include this punctuation.

  • Follow user interface capitalization and formatting.

  • Do not use descriptors like buttion or option button unless the descriptor helps avoiding confusion or awkward phrasing, or if necessary to avoid confusion with another element.


Writing rules

Related topics

Standards for writing and grammar rules

  • Microsoft Style Guide, 4th Edition, Microsoft Press, Washington, 2012, ISBN 978-0-7356-4871-5
  • Chicago manual of Style, 16th Edition, University of Chicago Press, Chicago, 2012, ISBN 978-0-226-10420-1

Topics