documentation guidelines

[Alexander Kirillov <kirillov math sunysb edu>]

Hi, guys,
here are some minor suggestions for "documentation guidelines" - if
everyone agrees, we'll add them to GDP -Howto (being written now). 
-------------------------
1. Application documentation should say which version of the
   application it documents, e.g. 

    <sect1 id="intro">
      <title>Introduction</> 
       <para>
     blah-blah-blah
 This document describes version 1.0.53 of The GNOME Application 
      </para>
	</sect1>
--------------------------
2. Documentation should contain names of authors of the application
   itself and the documentation, along with info for submitting bug
   reports. For small docs, the suggested way is to put it in a
   separate <sect1> at the very end of the document, e.g. 

  <sect1 id="authors">
    <title>Authors</>
     <para>
      GNOME Application  was written by GNOME Hacker
      (<email>hacker@gnome.org</>). Please send all comments, suggestions,
      and bug reports to the <ulink type="http"
      url="http://bugs.gnome.org">GNOME bug tracking
      database</>. Instructions for submitting  bug reports can be
      found on-line at <ulink type="http"
      url="http://bugs.gnome.org/Reporting.html">
      http://bugs.gnome.org/Reporting.html</>.
      </para>
    <para>
      This manual was written by GDP Member
      (<email>you@your.address</>). Please send all comments
      and suggestions regarding the manual to the GNOME Documentation
      Project at <email>docs@gnome.org</>. 
      </para>
    </sect1>
----------------------
3. If you use any of the trademarks, you should add to <legalnotice>
   section appropriate legal junk, e.g. 

    <legalnotice>
      <para>
	This document can be freely redistributed according to the
	terms of the GNU 
	General Public License.
      </para>
      <para> Linux is a trademark of Linus Torvalds</para>
      <para> UNIX is a trademark of X/Open Group</para>
      <para> Macintosh  is a trademark of Apple, Inc.</para>
      <para> All other trademarks are property of their owners</para>
    </legalnotice>

-----------------
Do you agree with these? or do you think there are better ways? Let me
know.

   
Now, two more sensitive issues:

A. Why many docs (in particular, users guide) contain sinister
reference to "other operating systems"? Is there a taboo on saying
"MS-Windows" or "Macintosh"?  For me, it sounded childish.

B. Should we include in guidelines a suggestion to use term GNU/Linux
rather than Linux? 

Please do not consider it as a flamebait. We all know what RMS has to
say on the matter. I am not asking for a discussion on whether he is
right (I personally think he is) or whether it is not worth the
inconvenience. I am just asking, whether
this should be decided as a matter of GDP guidlines or should be left
to individual authors. 

Best,
Sasha