Re: CVS, templates, and changes to docs

["David C. Mason" <dcm redhat com>]

Dan Mueth <d-mueth@uchicago.edu> writes:


> For documentation, a lot of these decisions are already taken care of by
> Dave when he writes the stylesheet.  However, we still have a fair number
> of decisions to decide upon and stick to in order to make our
> documentation consistant, readable, navigable, and professional-looking.  
> Deciding on a window manager and theme was one example of where we had to
> agree on a standard for all the docs to use, even though many people
> disagreed on what window manager/theme to use.  In this case, it was much
> more important to decide on a standard and stick to it than to find the
> "right window manager".  There are many more small places where we have
> not officially discussed and voted on issues, but it is essential that we
> agree on a standard. 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.

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.

Perhaps I am wrong - any more thoughts anybody?

Dave
-- 

          David Mason
        Red Hat AD Labs

        dcm@redhat.com
  http://people.redhat.com/dcm