discuss: [jfleck@inkstain.net: GNOME Documentation Style Guide]
Subject:
Re: [jfleck@inkstain.net: GNOME Documentation Style Guide]
From:
Gregory Leblanc ####@####.####
Date:
8 Jul 2001 00:46:03 -0000
Message-Id: <994552936.2412.0.camel@peecee.linuxweasel.com>
On 05 Jul 2001 22:41:53 -0700, David Lawyer wrote:
> On Wed, Jul 04, 2001 at 04:54:45PM -0400, Greg Ferguson wrote:
> > On Jul 4, 4:59pm, Dan York wrote:
> > > Subject: Re: ####@####.#### GNOME Documentation Style Guide]
> > > David,
> > >
> > > > Take a look at this Style Guide put together by the GNOME project. It
> > > > is most excellent.
> > > >
> > > > http://developer.gnome.org/documents/style-guide/
> > >
> > > I, too, found it very useful.... [...]
> >
> > (fyi)
> >
> > I added a link to the guide in the LDP author's resource area...
> >
> > http://www.linuxdoc.org/authors/#resources
> >
> > Excellent guide. Well-done.
>
> Well, I looked at some of it and I disagree. There are likely
Just a quick note... This document is targeted at the GNOME
documentation project, not at the LDP. Completely different culture and
environment. Many of the points that you make here are valid in the LDP
context only.
> > Avoid topical expressions
> A common saying might be popular and widely used today, but
> tomorrow the same saying can convey something altogether
> different.
>
> If others can modify the doc, then when it loses popularity it can be
> removed.
Topical expressions are very dificult to translate, and quite often
don't mean the same thing to a US reader as they do to one from the UK.
Sometimes they don't even mean the same thing across the states.
> > 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.
If you're actually writing a HOWTO, none of the steps should be
dificult, and any that have the potential to be, should be broken down
further. I'd rather see "this setup requires advanced knowledge of how
DNS and bind works" than "this one is really hard to do, here's some
vague steps", but perhaps it's just me.
The only way that I can see being able to make valid statements about
the dificulty of a tasks is by either knowing (which is nearly
impossible) or stating your target audience. Configuring an X server
might be extremely challenging for somebody who's been using Linux for 3
days, but it will probably be trivial for somebody who has deployed
hundreds of Linux desktops in an enterprise situation.
Ugh, I'm getting wordy again. TTYL,
Greg
