newbies/advanced users: for whom we write?

[Alexander Kirillov <kirillov math sunysb edu>]

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:

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

- Documentation should be complete: all program's capabilities and
  options, availbale to the user, must be described. 

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

  

 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.


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