This chapter is used in the following
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.
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.
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.
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.
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.
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:
What is the purpose of this exercise?
What do I wish to accomplish?
Background information (If applicable)
are concepts that are useful to the reader before he or she starts
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.
Prerequisites (If applicable)
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
Highlight potential hazards (If applicable)
admonitions if necessary to identify real potential risks or important
Expected results (If applicable)
the expected result(s) from the exercise. If the actual results do
not match the expected results, refer to additional exercises or procedures.
Use a numbered list. If a sub-procedure
is required within a step, use alphanumerical characters to identify
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
Use meaningful verbs. Use clear, present tense imperatives.
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.
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.