Re: CVS, templates, and changes to docs

[Dan Mueth <d-mueth uchicago edu>]

On 28 Apr 2000, David C. Mason wrote:

> > For example, we should discuss the Panel in the same
> > way.  Whether we use "panel", "Panel", "<interface>Panel</interface>", or
> > something else is less important (IMO) than the fact that we should all do
> > the same thing.  Whether we use "<itemizedlist>" or "<variablelist>" to
> > list the items in the right-click menu is less important than agreeing on
> > using just one and sticking to it.  
> 
> I don't think the template is the place for this type of thing. I
> think the handbook is. We can't know when someone will use the word
> Panel and sticking a <!-- use Panel instead of panel--> and bunch of
> other comments in the templates is *not* easy reading. However,
> reading a section in the Handbook on 'conventions used by the GDP' is
> *much* easier to read and understand.

Sorry - I think I must have been unclear.  What I meant to say was: (1)
things that are repeated frequently by different authors and/or in
different documents should be standardized to some extent. and (2) things
that are repeated frequently in a certain type of document should be
included in the template.

So the template should not have a thousand comments saying things like
"<-- If you happen to use the word Panel, make sure to use ... markup -->"
However, since almost every application has a menu bar across the top of
it, we should include a description of the menu bar and its contents in
the template with the correct markup.  (Here "correct" is a standard we
decide on, not something that is always strictly defined by the DTD or
other constraints. There are many arbitrary choices to make here.) Since
every application has authors (and bugs, and a license, etc.), we should
have sections in the template for these.

I think it is pretty clear which things belong in the template and which
things should only occur in the Handbook.  In fact, it would be nice to
have some things in the template and not have to discuss them in gory
detail in the Handbook.  For example, somebody (sasha?) put a very nice
comment besides the "<sect 1 id="index.html">" at the beginning of the
applet template saying that people should not change this id. Of course if
the Handbook was a strict and complete rulebook, then we could put this
there too.  But from a practical point of view, putting it in the template
is much more effective and helpful.  I would hate to have to constantly
refer to the Handbook when I write each doc.  Another good example (sasha
again I think) is having the commented out section on how a translator
should recognize themselves in the copyright and authors section.  It
would be a nuissance if every time a translator translated a
document, he/she had to cut and paste this out of the Handbook.

> I understand your point about wanting to get consistency out of all of
> the writers - whether it is truly possible in an open project is yet
> to be determined - but I also don't think the templates are the tools
> of choice for communicating this.

I have no reason to believe that the open source model works well
for writing good software but not for writing good documentation of it.  
If I believed this was true, I would not be spending my time writing
documentation.  I think we should expect the same level of quality in our
documentation as the developers put into their code.  

Dan