CVS, templates, and changes to docs

[Telsa Gwynne <hobbit aloss ukuu org uk>]

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

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.

One of the docs I did was the whereami applet.

I just had email from John Kodis, the applet author, suggesting that
"The whereami applet is.." was slightly more grammatical that "Whereami
applet is..." (true) and that it would be nice to include the area
measurement function in the documentation for it. 

I looked at the diff and boggled. Because my original had both the
"changes" he was suggesting. I had started it with "The..." and I had
included stuff details about the area management. Someone had gone 
through and removed them. They also altered all the 

<variablelist>
 <term>Wotsit</term>
  <listinfo>
   <para>
     The wotsit does this..

to 

<itemizedlist>
 <listinfo>
  <para>
    Wotsit&mdash; this...

which is just a markup difference. 

I had had no idea that the changes to the content had happened. The 
only reason I knew was that John Kodis commented on the lack of 
something I'd actually put in originally. 

cvs log in the gnome-applets/whereami/docs/C directory tells me 
that the only changes were Dan, adding a screenshot (thanks) and 
"correcting to conform to template". If Dan didn't do the changes 
I'm referring to, apologies to him.

I have been meaning to bring this up anyway, but this has precipitated
things a little.

I think these changes were a little unnecessary. Are we now expected
to be word-for-word template-conforming? That's... well, at the least,
going to be tricky for some of the more feature-laden ones. 

I really really think we're relying too much on the templates. When
it gets to the stage of removing "The" from the start of a sentence,
I think we're going way overboard. Especially because it's more
correct to have the "The" there! I had always assumed its omission
from the template was a typo.

If we're actually going to be word-for-word based on those templates,
then I hate to say it, but I think they need quite a few changes. I
don't mean we should scramble to do it for 1.2, but I think they
would have to be changed. _If_ we're going to do that.

Furthermore, I really don't think we should be following them that
slavishly. I think they should be guidelines, not dictates. I have
to admit that I felt quite irritated that someone had changed those
to that extent and hadn't mentioned it.

I know that I asked people to feel free to add screenshots and change
the licences and so on. And I that was very busy offline and didn't
actually look at the results. But I didn't realise that bits would get
removed and even trivia like "what kind of list" was going to get
altered, too. (For what it's worth, I think <variablelist> is better
than having to separate off something in a different list and use
an em dash, and I have kept meaning to bring this up.)

Also, it seems such unnecessary work!

Telsa