users guide - some thoughts

[Alexander Kirillov <kirillov math sunysb edu>]

       Hi, guys,

now that we have, as Dave puts it, "revitalized" gnome documentaiton
project (see his e-mail to gnome-announce list), I have some thoughts
about the users guide that I'd like to discuss.


1. In the users guide, there is documentation for exactly 2
applications: CD player and gcal. Why those two, of hundreds? Any
special reason? As for applets: most of them are covered, but some are still
missing (for example, keyboard switcher applet). 

Of course, I understand that Dave has only limited time. I am asking
what the goals are. Do we intend to put in the users guide
documentation for all the applets? then let's list those which are not
there yet, and ask people for help - this can be done quickly. What
about applications? We obviously can't have in users-guide help for
ALL applications. Any reasonable criteria? Maybe, just LIST all
applications with a brief comment - as in gnome sofware map - and
links to their documentation, so that users know what they have
available without the need to guess what "Ghex" in menu might stand
for? Ideas, anyone?


2. I tried to read the users-guide from the point of view of someone new
to Unix and see what are prerequsites. I found it sufficiently
self-contained; however, there are several things that it does rely
on:

a. General stuff on Unix filesystems: what symbols can be used in
filenames, what the notations like ./, ../, ~/ etc stand for;
permissions and users; wildcards. 

b. Symlinks

c. Mounting/unmounting 

Of course, it is covered in countless books, "getting started" guides,
etc. But still, it might be worth it to add an appendix "If you are
new to Unix" - or, at the very list, provide a link so that people
know where to look for it. If you think all users know it anyway, you
are wrong - if I go around our dept, which uses a network of Suns and
Linux boxes, and ask people "what are symlinks"?, most would have no
idea. Apparently, Dave also felt the need to address some of this, so
he included some info on mounting CD drives, even going as far as
explaining how to hand edit /etc/fstab - which, btw, looks
absolutely out of place in the chapter on CD player, so it better be
put in an appendix. 

So: do you think it is worth doing? If so, I'd volunteer to write such
an appendix (I am familiar with DocBook). Comments? 


   Sasha