Re: template stuff

[Telsa Gwynne <hobbit aloss ukuu org uk>]

On Tue, May 16, 2000 at 03:50:22PM -0500 or thereabouts, Eric Baudais wrote:
> 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.

I don't leave the non-translator bits in, although I leave the ones
which will - we hope - be useful for translators. But I don't think it
matters hugely either way. I just find the comments distracting, and
in a small window or at the console, I like to be able to see more.
So I take them out :)

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

I absolutely agree in this. If the template doesn't make sense for the
app, do it differently. 

Telsa