Re: CVS, templates, and changes to docs

[Dan Mueth <d-mueth uchicago edu>]

On Fri, 28 Apr 2000, Telsa Gwynne wrote:

> /* Dan, please don't take this as a public flame. I'm sending it to the
> list because CVS is something we're all using and if we have a problem
> (and I think we do) with CVS, it's best everyone knows. */

Point well taken.  These are important issues we need to discuss and
decide upon as a group.  It affects all of us and all of the docs we
write.

> When I did the majority of the applet docs I did, the templates weren't
> about (when I started) or stable (when I finished). I liked the idea of 
> templates for two reasons: first, it would be valid DocBook that people 
> could use whilst they were getting up to scratch; and second, we could 
> make sure we covered all the bases by putting things like credits, bugs, 
> key-bindings (actually, we don't have that in much) and so on. In effect, 
> we could use them as mental checklists.

Yes.  My original opinion of the templates were that they were there to
help new writers join the GDP and become productive quickly and
painlessly.  I think they have served this purpose fairly well.

As the GDP filled out the docs and grew in number of people and writing
styles, and as the templates evolved into a more mature and
professional-looking document template, my perspective on the value of the
template changed.  It became clear that we were actually succeeding in
producing a lot of documents and that looked they looked pretty good.  
However, any professional document or system needs a level of
self-consistancy.  Dave gave a nice (albeit brief) discussion of this in
his GUADEC talk, explaining how the toughest challenge of a documentation
team is achieving "one voice".  On a less stylistic and more
technical level, the way we markup a document, the terminology
used describing the desktop, the overall layout of the document, the use
of figures, the naming of sections, the use of capitalization, etc. all
needs to be self-consistant within a document.  (From the user's
perspective, all the applets, and perhaps all the documentation that ships
with gnome-core, gnome-applets, etc. comprise a single
"document".  Plus the User's Guide will literally bind these into a single
coherent book.)

I believe and agree that we must give the application or documentation
author the flexibility to innovate.  If somebody wants to add a pull-down
menu at the top of their app called "Scripts and Plugins"(Xchat), this is
fine.  And if somebody wants to add a section to a document titled
"Example Scripts", this is great.  However, if somebody wants to move the
"Help" menu item from the right edge to the left edge or rename the About
dialog the "Info" dialog, I would object.  The person may have a good
reason why the term "About" is not a good choice, but these sorts of
conventions exist to make the the interface predictable and consistant.
Without them we would actually have to read the manuals for every program
we want to use.

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 think this applies to many different parts of the templates.  The
templates are not perfect, or even close.  However, when it comes to the
sorts of things that I mention above or Telsa has brought up, I think
using the template as a standard is important.  If we find problems in the
templates, the solution is to fix the template, not to have each person
just disregard the template and do their own thing.  That is the only way
to get a good template and the only way to produce a quality body of
documentation(IMO). (A "quality body of documentation" is different from a
"body of quality documentation".)

So in situations where the same thing(terms, section labels, lists,
images, etc.)  occurs in various documents, I think standards should be
determined and followed.  There is always room to add more stuff to your
document if the template does not cover it.  But replacing one word for
another word (or one tag for another tag, or one theme for another theme)
which means about the same thing will only confuse the reader and make the
documentation look disorganized and unprofessional.

That is my opinion and I had been (wrongly?) assuming everybody agreed
with this. I'd like to hear everybody elses opinion on this and any
arguments to the contrary.

Dan