21/03/2010
documentation, english, FLOSS, not to do
3 commenti

What You Shouldn’t Do

For your eye pleasure, directly from the Desktop Help Summit, the 10 top things you shouldn’t do when writing documentation. Enjoy.

Hi guys,

Top 10 things not to do with your docs:

Reading the interface back
————————–
∘ Don’t document the entire interface – it’s safe to assume certain
things are obvious and don’t need to be discussed.
∘ Don’t read back the interface – people can figure out that the Open
button opens something.

Not aiming at a consistent level of technical expertise
——————————————————-
∘ Say something basic and something advanced in the same sentence, e.g.
“Click Open to open the document” in the same sentence as “you need to
install GRUB after you partition.”

Verbosity
———
∘ Explaining things at great length, in the same topic as where you give
the instructions.
∘ Just link off to a conceptual topic instead.
∘ Assume people will skim – don’t make them read loads of intro before
you get to the instructions.

Incorrect level of formality
—————————-
∘ It’s OK to use contractions.
∘ Still use reasonably formal language (i.e. don’t be crazy or overly
friendly), but don’t make it sound dry. it should flow.

Lack of context
—————
∘ Need to give context so people understand what is going on.
Confidence.
∘ Don’t just write a big list of commands.

Over-use of screenshots
———————–
∘ Only use them to illustrate a point.
∘ Don’t need to use them everywhere, the user is probably looking at the
screen anyway.

Leaving out steps or using too many steps
—————————————–
∘ Need to choose the appropriate level of detail. No need for one step
per mouse movement.
∘ Likewise, don’t miss things out if they seem obvious, just cover them
very briefly.

Documenting things which no-one cares about
——————————————-
∘ Document things that people need to know about, don’t just scratch an
itch.

Putting more than one topic in one document
——————————————-
∘ Results in long, rambling documents.
∘ Confusing, difficult to link to, overlap.
∘ Users confused by irrelevant, buried information.

Don’t talk down to or patronise your users
——————————————
∘ Using phrases like “obviously” can make people feel bad if it’s not
actually obvious.

If anyone can find one or two examples of any of these mistakes, that
would be cool.

Does anything come to your mind?

Oh, BTW, buttons are on the left.

3 commenti
  1.  

    Pingback: Milo Casagrande: What You Shouldn’t Do | TuxWire

  3. The word “simply” is another peeve of mine (in addition to “obviously,” thanks for pointing that out). If it was so simple, why is the documentation needed? 🙂 The answer is that we document things in part so that people who are having difficulty can find answers to their problems. If we say it’s simple, it’s as if we’re saying, “You should really understand this already,” which again is patronizing.

    Thanks for the blog.

    Rispondi ↓

Lascia un commento