Re: Hello

[Dan Mueth <d-mueth uchicago edu>]

On Sun, 17 Sep 2000, Tim Riehle wrote:

> 
> I just signed up for the list and would would like write documentation for
> gnome-mines. I have experience with CVS, HTML and LaTeX and have been
> able to successfully compile the SGML application template.
> 
> Tim Riehle

Tim,

Welcome. It is great to have your help. I'm glad to see that you have your
system set-up and running already - that tends to be the hardest part of
writing docs.

We are in the process of changing our document style from that used in the
current (old) templates to a more user-friendly writing style.  If you
look at the templates or the documentation shipped in GNOME 1.2, you will
see that they focussed on explaining the user interface.  We would like to
move to a more concept-oriented or task-oriented style.  We don't have any
finished GDP docs to show you what we mean, but perhaps this is good at
this point since we haven't really explored the possibilities yet.  So, I
would encourage you to use the DocBook markup in the template, and some of
the boilerplate stuff (copyright, Known Bugs section, License section,
Authors section), but to take the liberty to mold the main part of the
document however you see fit.  Especially for games, I think the current
template is particularly poorly suited.  For games, you will probably want
sections along the lines of "Game Objective", "Game Rules", "Winning",
etc. instead of sections like "Usage", "Customization", "Basic usage", and
"Menus".  For situations where a detailed description of the menus or
dialogs seem appropriate, it may be best to put this at the end of the
document (as more of a reference or appendix) instead of as the primary
part of the document.  This allows the "Help" button in the preferences
dialog to link to a page describing the dialog in detail, but does not
bore a reader who just wants to learn how to play the game.

Dan