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

[James Cope <jcope mpc-data co uk>]

>>>>> "Telsa" == Telsa Gwynne <hobbit@aloss.ukuu.org.uk> writes:

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

Despite not being able to support it fully at the moment, it does no
harm to begin work on a glossary now. Then in the future when it is
better supported by the help browser we could get a good glossary
linked in to the documentation quite quickly.

Something that might be useful: a database of glossary entries that
authors could all add to and update through some form of web front
end, something akin to DocTable. It would then be fairly easy to get
that database into a suitable format when the time comes. This would
help reduce the duplication of effort for example.

We might not be able to have the nice on-the-fly support right now,
but with a glossary as a seperate document, we can at least say
``Refer to the Glossary.'' Much the same as how ``Refer to Appendix
C'' or ``Refer to the GNOME users guide'' would be used in Sasha's
example. 

This does not mean however that we shouldn't introduce new terms the
first time they are used. I believe that even if a term is defined in
a glossary, it should still be introduced to qualify it's
meaning. This particularly helps if a term, acronym or abbreviation has
more than one meaning.

    >> 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.

    Telsa> This also covers, "This is a relatively complicated
    Telsa> subject: either skip it completely or refer to the more
    Telsa> complex documentation" as being a bad idea, I imagine. I
    Telsa> can think of certain situations where it would be terribly
    Telsa> tempting to cop out and do that otherwise!
 
Forgive me if I slightly misunderstand Telsa's point here. I seem to
be able to read it as having two different meanings.

Having a Basic and Advanced sections makes it tempting for an author
to be lazy and easily gloss over important points because they are
difficult to express, which is bad (This is one way I read Telsa's
comment).

Having a statement that refers the reader to more advanced
documentation is good (The other way I read it).

Personally, I don't like having dedicated Basic and Advanced sections
in documentation but that's just me. I prefer a method that leads the
reader gently through possibly complex topics and helps direct them
away from difficult areas by referring to complex documentation (Umm,
that's another way of interpreting Telsa's point I think, sorry!).

(Off Topic: Does anyone else find it frustrating when in a book you
read: ``It's probably best to skip this section and come back to it
later when you feel more confident.'' I always read what's there! It's
like saying to a child ``Don't go into the scarey forest.'' You've
just got to find out what's in there! :-)

    Telsa> I think these, or something very akin to them, should go in
    Telsa> the guide, yeah. 

Yes I agree. Sorry if I sound like I'm nit-picking. All the points
raised are only good ones and they should all be mentioned in one form
or another in the Documentation Handbook.

My main point was that I think we do need a glossary, both for the
user AND for authors. That way the authors know if they should be
using the term `left-click' or `button-1.' The user/reader then
knows what the author means by `left-click' or `button-1'. Things like
that should be in the glossary, it helps authors and readers.

Eek, I'm rambling.

James.