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

[Telsa Gwynne <hobbit aloss ukuu org uk>]

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

I intended to say the first. But it was late and I was tired!

An an example, I have a book called "Learning Red Hat Linux".
It assumes that of the two installations (pretty graphics, simple,
limited options; and not-so-pretty, more choice) you will use the
first. It explains that, and says things like "You can use the
expert mode install if you need something different"; or "if you
cannot select the correct mouse at this stage, you can do it after
installation" -- and then nowhere does it tell you how to use
expert mode in any depth, nor does it tell you how to configure
your mouse type post-installation. That's the error I really
want to avoid. In addition, I fear that if you split into simple
and expert or easy and advanced or whatever, and then omit a
couple of things from the more complicated one, the reader is
never going to be sure where to look for things because s/he has
looked in vain for the ones that were omitted. Is it in the first part?
The second part? Somewhere else?


In gtop (again, just because it's one I know), I tried to explain
things in a logical order. At the end I put a "References" or 
"Further Information" section, listing the sources I'd used which
people could go to for further information: man pages, info pages,
/usr/doc and an essay on the web. I don't know whether that's the
right thing to do or not. But it seemed to work there. 

> 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

I think it can be hard to make the simpler stuff stand alone and
be accurate when you do that. We could possibly do it with the
use of <note> or something similar. 

> 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! :-)

Yes. The only time I've ever skipped entire sections is in Andrew
Hodges book about Turing. This was cleverly done. Parts of the book
clearly had to explain what Turing was working on and why it was
important. It explained the basics of the maths and its relevance
in the same font as the majority of the book. It would then switch
to a smaller font and go into horrible, horrible mathematical detail.
Since I had trouble enough following the simple explanations, I 
didn't bother with the small font stuff. I tried to wade through 
one and that was enough!

> Yes I agree. Sorry if I sound like I'm nit-picking. All the points

Nit-picking can be good :)

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

We keep talking about this on #docs. What I'm finding now is that
I'm writing one thing - as in the applet docs where I used button 1,
button 2, etc. And then the big all-applets-together doc has suddenly
acquired a "Right Click Menu" heading and other things. So yeah, we
need something. I had to rewrite the last batch of applets I was
messing with to fit into that (despite the fact that I left-click..)

I'm sorry. I will, reluctantly, go along with this if I'm the only
person who feels this way, but "left-click" and "right-click" are
_wrong_:) I was looking at trackballs the other day, and the buttons
are all over the place. Some mice have only two buttons, and middle-click
is more accurately "both buttons together click". My husband has a
machine with a stylus rather than a mouse, where the buttons are
indicated by different numbers of taps of the screen. (Dead cool;
I want one.) They may be accidentally right for the majority of users, 
but they're still wrong. 

Oh: the other thing on a glossary: I think it should be self-contained.
We could put places for further information, I suppose. But if 
someone is reading a glossary entry after being referred there, the
last thing they want is another reference to another location. So
there has to be enough information there for a basic understanding 
of the word without extra hunting about for docs.

> Eek, I'm rambling.

Likewise:)
 
Telsa