discuss: [jfleck@inkstain.net: GNOME Documentation Style Guide]
Subject:
Re: [jfleck@inkstain.net: GNOME Documentation Style Guide]
From:
"Mariusz Pekala" ####@####.####
Date:
7 Jul 2001 08:09:30 -0000
Message-Id: <004c01c106bc$100fe520$0201a8c0@wmbr.com.pl>
From: "David Merrill" ####@####.####
> > >> Avoid talking down to your reader
> > > There are few experiences more irritating for a user than
> > > documentation that says an action is easy or quick, when in
> > > fact the user can not complete the action. Do not qualify or
> > > prejudge actions. Stay factual.
> > >
> > >It's important to give the reader some idea of the difficulty of
> > >a task. It's not only so that the reader will know about how much
> > >time to allocate to it, but also so that the reader can decide is s/he
> > >wants to undertake it at all.
> >
> > This is the absolute most important. This linux shit is hard for most
> > people. Don't make them feel stupid.
>
> Absolutely!
Oh, no! Sometimes you should make me feel stupid.
If I know that 'this action' should be easy, and if I find it not easy it means that I have to learn more. On the other hand if some guru states that 'this action' is easy, and I find it easy this means I am almost like this guru. This makes me feel better. :-)
Additionally if a lot of actions are described as 'easy' then you increase the possibility that I will take more care to perform a task that is desribed as 'hard' or 'dangerous'. Also if you describe some action as quick, and my machine seems to be working for an hour, then I may start suspecting that something goes wrong. This is my job to react or wait, but you give me a clue what to expect.
So, I vote for qualifying and prejuding actions.
--
Jezdzisz konno?
Ten konkurs jest dla Ciebie! [ http://konkursy.onet.pl/emarket2/ ]
