Re: template stuff

[Eric Baudais <baudais okstate edu>]

Greg-

Gregory Leblanc wrote:
> 
> I haven't looked to see if there's a newer template than the one that I used
> to create the gcalc docs, but I've got a couple of questions on that one.
> First off, what comments should be removed, and which should not?  For
> example, the section for translators is commented out, but should I leave
> that there so that they can find it if/when they go to translate it, or
> should I take it out because it's a "comment"?  I think there are a couple
> of other similar sections (maybe they're just other "translators" sections).

I think the comments that should be left in are the translator
comments.  I also 
don't see why you can't leave in the section title's comments.  I think
those 
help differentiate the different sections in the sgml.

> Second, why isn't the "menu" section consistent?  I understand offering two
> ways of doing it, but documenting different menus differently doesn't make a
> lot of sense.  Perhaps that should have just another option in a comment, or
> at least some more comments there explaining why there are two different
> examples.

I've used the templates for a couple docs now and don't see that there
are two 
different menus being described.  There is the menu bar and the toolbar,
but 
those are different types of menus.

I also thinks it needs to be emphasized, again, that the templates are
just 
guides for documentation.  The applet templates should be followed more
closely 
because the applet documentation is supposed to look more alike.  I've
started 
one doc from scratch and it actually came out pretty close to what the
templates 
show.  I would encourage writers to show creativity in organization and
format of 
their documentation as well as in the text.

Eric Baudais