Re: documentation guidelines

[Telsa Gwynne <hobbit aloss ukuu org uk>]

On Mon, Jan 24, 2000 at 10:57:56AM -0500 or thereabouts, Alexander Kirillov wrote:
> 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

Good plan.

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

Don't many of the GNOME documents already have a by-line at the
start, in all the bookheader/artheader stuff? But I agree: feedback
addresses for programmer and documenter (if different) are good.

>       (<email>you@your.address</>). Please send all comments
>       and suggestions regarding the manual to the GNOME Documentation
>       Project at <email>docs@gnome.org</>. 
...

And that will solve the problem of what happens when people move on,
change email addresses, suddenly recall they should be revising, not
reading email, etc :)

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

Can someone tell me how this works? I nicked the layout of the
gtop docs from the gnome-terminal one, and this section below
magically created the legal notice page although I had done 
nothing to make this happen. I'm still baffled by how this happens.

Someone will have to find a nice list of trademarks and copyrights,
then. There's some amazing ones out there. If anyone has access to
"In Search of Clusters" by Gregory Pfister, they will be enlightened
and entertained by his list of trademarks with his annotations mixed
in. "Ethernet is a trademark of Xerox Corp. (I never knew that!)"
and so on :)

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

So how's this work to generate the extra page?
    
> 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.

I hadn't noticed this until you pointed it out, but I agree. It
makes sense sometimes, but there are occasions when people use it
unnecessarily. I know nothing about Windows, but I do have a vague
idea what the Next interface was like (I use windowmaker :)). Other
people know about what Mac interfaces are like. Putting "other OSs"
is not always very clear, whereas a specific reference to the other
in question can help someone think, "Oh, that thing" or "Never seen
that OS, so I don't need to worry what this was called there."

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

Interesting question. I take the point about GNU/Linux, but then
we get into the issue of, if the point is to highlight the GNU-based
origin of many of the apps and utilities, how to refer to systems 
where it's a commercial UNIX but it has a bunch of GNU tools on it: 
a situation that may arise if you have got the GNU tools to compile 
and install GNOME on Solaris or IRIX. As I understand it, if you're 
following RMS's reasoning, then you should refer to those as GNU/whatever, 
too, to indicate that the userland stuff is GNU packages? 

Perhaps this should be left to individual authors of the programs
involved, and for general non-program-specific documentation be
left to the writer? The GNU aspect isn't going to be left out:
it's the G in GNOME, after all :)

I don't know whether this is the right place or not: Dave told
me after looking at some of my stuff that there are conventions
to do with using DocBook which were not something I had picked
up from the book (and I still maintain that, by the book, they're
wrong, but hey :)).

Perhaps putting those, and any more that crop up, into GDP guidelines 
would be worth it?

The two I have run afould of so far are:
  o "Even if it looks and acts like a button, if it's not "technically"
  a button (and a definition would be good here, please), then mark it
  up as a <guilabel> rather than a <guibutton>"

  o Don't put things like <guimenuitem> and stuff inside <term>
  because it gets marked up funny by the Gnome-specific stylesheets.
  (and I still think the fix is to alter the stylesheet: the book
  says it's allowed :))

Telsa