| In the
documentation world, “minimalism”
is a fancy word for a commonsense
practice. In basic terms, it means write
to your reader and keep it simple. The theory itself
has a lot of twists and turns. If you
want to read a great – but slightly
wordy – book on the subject, check
out the book “Minimalism Beyond the
Nurnberg Funnel”, 1998, edited by
John Carroll.
In the
meantime, if you can tick every item in
the following checklist, you’ll be
well on your way to usable online help
that both your readers and your managers
will thank you for.
Helpful
Help Checklist
1. Base
the help on real tasks (or realistic
examples)
2.
Structure the help based on task sequence
– Chapter headings should be goals
and topics should be tasks
3.
Respect the reader's activity – this
is generally more about what you don’t
do than what you do. Don’t waste the
reader’s time by diving off into
tangents
4.
Exploit prior knowledge and experience
– Draw the reader’s attention
to previous tasks, experiences,
successes, and failures
5.
Prevent mistakes - "Ensure you do x
before doing y"
6.
Detect and identify mistakes - "If
this fails, you may have entered the path
incorrectly"
7. Fix
mistakes - "Re-enter the path"
8.
Provide error info at end of tasks where
necessary (rule of thumb, one error info
note per three tasks is a good average)
9. Don't
break up instructions with notes,
cautions, warnings, and exceptional cases
- Put these things at the end of the
instruction, wherever possible
10. Be
brief, don't spell everything out,
especially things that can be taken for
granted
11. Omit
conceptual and note information where
possible, or link to it. Perhaps provide
expansion information at the end of the
topic, plus maybe a note that there are
other ways to perform the task/goal, but
this is the easiest
12.
Sections should look short and read short
13.
Provide closure for sections (e.g., back
to original screen/goal)
14.
Provide an immediate opportunity to act
and encourage exploration and innovation
(use active invitations to act, such as,
"See for yourself..." or
"Try this..." rather than
passive invitations such as, "You
can...")
15. Get
users started quickly
16.
Allow for reading in any order - make
each section modular, especially goals,
but perhaps tasks (definitely if they can
be performed in different order)
17.
Highlight things that are not typical
18. Use
active voice rather than passive voice
19. Try
to account for the user's environment in
your writing
20.
Before writing anything, ask yourself
“Will this help my reader?”
By
building these practices into your
documentation process, you’ll find
that your online help becomes easier to
write, shorter, and far more usable for
your reader. What’s more, your boss
will love you!
|
Articles