Home> About us > Branding guidelines > Documents > Manufacturing documents >

Chapter specification - Practical exercises

This chapter is used in the following manuals:

Practical exercises can be added as a separate chapter or appendix whenever useful to increase the reader’s understanding of the product features and functions.

Exercises are written as procedures using numbered steps. If necessary, specific exercises may be aimed at specific users or user groups.

Chapter structure and section titles

Since several exercises may required, a good solution can be to use sections to collect exercises related to the same features or functions.

Due to the different nature of our products, it is not possible to define a generic structure with fixed section names.

Exercise titles

Each exercise is normally provided in a separate section. You may however find it useful to keep each exercise as a separate information element, and provide the section, exercise title and the accompanying section ID local in your XML document. That allows you - if necessary - to include essential exercise more than one time in a big book.

Always use a descriptive title for your exercise. Create a title that the reader can recognise and relate to.

  • Find titles and names that the reader would use.

    Do not use specific function names from menus and dialog unless these are a part of the reader’s everyday language.

  • Use the gerund form in the title.

    • Use “Setting the date”.

    • Do not use “How to set the date”.

Topic structure

Structured topics are essential to create modular documentation. By breaking down the information to easily recognizable elements that comply to a defined structure, the elements are easier to locate and reuse in other sections, chapters or books. Makes sure that file names reflect the element’s position in the structure.

Recommended structure for exercises are:

  1. Purpose

    What is the purpose of this exercise? What do I wish to accomplish?

  2. Background information (If applicable)

    These are concepts that are useful to the reader before he or she starts the exercise.

    It is important that you distinguish exercise and tasks from features. Limit the introduction to two sentences. Do not offer long explanations here, only key information. Refer to concept descriptions if more information is available and/or required.

  3. Prerequisites (If applicable)

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

  4. Highlight potential hazards (If applicable)

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

  5. Expected results (If applicable)

    Specify the expected result(s) from the exercise. If the actual results do not match the expected results, refer to additional exercises or procedures.

  6. 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.

    • Use “Set the starting time”.

    • Do not use “A starting time should be set.”.

    Do not provide multiple options for doing the same exercise. 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.

Topics

Back to