Re: documentation guidelines

[Karl EICHWALDER <ke gnu franken de>]

Alexander Kirillov <kirillov@math.sunysb.edu> writes:

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

This is useful info.  I'd recommend to store this info as an attribute;
maybe, in addition to your human readable text.

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

Also useful.  Please, consider to use entities:

<!DOCTYPE book [
<!ENTITY app-authors "GNOME Hacker1 (<email/hacker1@gnome.org/),
                      GNOME Hacker2 (<email/hacker2@gnome.org/),
                  and GNOME Hacker3 (<email/hacker3@gnome.org/)">
]>
...
<title>Authors</>
<para>
GNOME Application  was written by &app-author;.
...

|   ----------------------
|   3. If you use any of the trademarks, you should add to <legalnotice>
|      section appropriate legal junk, e.g. 

Unfortunately needed...

Please, think about an external file (entity) to be include by all
manuals:

<!DOCTYPE book [
<!ENTITY gnome-tm-list SYSTEM "gnome-tm-list.sgml">
]>
...
&gnome-tm-list;
...

where gnome-tm-list.sgml contains <legalnotice>...</legalnotice>; if
more appropriate, instead of SYSTEM you can use PUBLIC and resolve the
entity via a catlog entry.

Once you'll start to use private entities, think careful about namespace
problems.

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

That's an rhetoric issue -- the game we all play.  Maybe, it has
something to do with "damnatio memoriae".

-- 
work: ke@suse.de                          |
     : http://www.suse.de/~ke/             |          ------    ,__o
home: ke@gnu.franken.de                   |         ------   _-\_<,
     : http://www.franken.de/users/gnu/ke/ |        ------   (*)/'(*)