Re: newbies/advanced users: for whom we write?

[Telsa Gwynne <hobbit aloss ukuu org uk>]

On Thu, Mar 09, 2000 at 05:31:15PM -0500 or thereabouts, Alexander Kirillov wrote:
> 
> Hi all:
> 
> while reading some of GNOME manuals, I realized that they were written
> by developers for other developers, with little understanding of level
> of average user. Thus, I'd like to include in the Handbook some
> guidelines about what the documentation authors should expect from the
> reader. I wrote a very preliminary draft, included below. Since it is
> highly debatabable topic, i'd like to hear everyone's comments before
> actually puting this in the handbook. So: please read, and say what
> you think about it!
> 
> Sasha
> ----------------------------------------------
> 
> When writing documentation, please keep in mind that:

I'd suggest, "When writing user documentation" :) I know it's 
obvious at the moment, but the handbook does have some stuff
specifically aimed at developers (how to link help stuff in,
for example), and at the rate it's growing, it's entirely
possible it might end up including documentation stuff for
developers too :)

>  - Many users have little or no UNIX (or, more generally, computer)
>    experience. Many of them have no idea what abbreviations like PID,
>    PATH, URL, NFS, $HOME stand for, or understanding of notions like
>    symlinks, inodes, or mount points. It does not mean that they are
>    complete idiots(tm) - they may be very smart but know nothing about
>    UNIX internals - and why should they? Your documentation
>    should be written so that it is accessible - as much as possible -
>    to these new users, too.

Is it time we started thinking about a glossary for GNOME and UNIX
terms? Or -- and this is my thought -- are we better to leave that
until the new help browser arrives, when on-the-fly stuff is better
supported? (I know it's a long way off, but we have enough to do at
the moment; and by then we'll have a much better idea of what things
are getting explained more than once in different areas.)
 
> - Documentation should be complete: all program's capabilities and
>   options, availbale to the user, must be described. 

Something we don't have in the handbook specifically is key bindings.
Occasionally I discover an app has keyboard bindings when I accidentally
hit keys and Something Happens :) 

Options: someone pointed out that all GNOME apps typically have
	--help
	--usage
	--something else I forget for testing, and perhaps another
    something else for corba-y things (like the applets all have
    --activate-goad-server, whatever this means).

Are these something that should be documented for each program, or
should the common ones get moved to avoid duplication?
 
> Obviously, these two requirements contradict each other: there is no
> way you can explain what "real users id" of a process stands for (in
> gtop docs) to a new user. However, there are several ways you can try

Hey, I tried! :) (If it didn't work, please tell me what I could change.
The only thing I specifically decided against including was what the
memory maps showed: I left it at "graphical representation of the
information of the raw memory map. This information is probably not
something that most people will need (or want) to know" for good
reason:) On the one hand I had proof-readers like Sasha pointing
out the hard bits and suggestions for rewording, and on the other
hand I had one of the memory-management gurus saying "No! There is
a difference between <wording 1> and <wording 2> and only one is
accurate". My thanks to both, btw :) I tried to strike a balance, but
if it's too complex, say. My only defence is that gtop _is_ a complex
program and lets you see an awful lot of information!

> to satisfy both of them at least partially: 
> 
>  a. Explain all non-trivial abbreviations (at least, their first
>   occurence), e.g.  "URL (Uniform Resource Locator, most commonly
>   Internet address, such as http://www.gnome.org)".  It is OK to have
>   simplified explanation - it is better than nothing.
> 
>  b. Refer the reader to proper documentation: 
>    " mount point <footnote>If you are unfamiliar with the notion of
>    mounting and mount points in UNIX, please see Appendix C, "If you
>    are new to UNIX...", of GNOME Users Guide</footnote>"
> 
>  c. Give a simplified explanation for new users and then add more
>  detailed one for advanced users, clearly marking it as such:

That, I like very much. 
 
>  d. Separate the material into "basic usage" section for everyone and
>  "advanced"  section for advanced users, putting the warning "This
>  section is intended for advanced users..." in the beginning. Make
>  sure that "basic usage" has some value of its own, not only as
>  introduction to "advanced" section.

This also covers, "This is a relatively complicated subject: either
skip it completely or refer to the more complex documentation" as
being a bad idea, I imagine. I can think of certain situations where
it would be terribly tempting to cop out and do that otherwise!
 
> There are many similar possibilities - all depends on the specific
> situation. Choose whatever you like, but please make sure that you
> treat new user with respect: general attitude should be not "of
> course, you know how to configure XFree86" but "new users can do this and
> that (explained in simple terms); if you know how to configure
> XFree86, you can do more, as explained in this section; if you do not
> know but are willing to learn, try reading XFree86 manual which you
> can find there (reference)"

I think these, or something very akin to them, should go in the guide,
yeah. I wonder. I have a bunch of links for "how to write technical
documentation" and one day I am going to find time to sit down and
read them. Are there good online resources we can point to for that
kind of thing? I have a book called "The Plain English Guide" which
is about writing clearly. I winced when I read it. Almost everything
I routinely do is in there as a bad thing! But it does offer constructive
suggestions on how to alter things to make them clearer. Are there
similarly constructive things on the net?

Telsa