Re: CVS, templates, and changes to docs



Telsa Gwynne <hobbit@aloss.ukuu.org.uk> wrote some good stuff:

[the big snip]

I am going to have to agree whole-heartedly with Telsa here. The
templates were created, and are there, to: 

a) help people who have never used DocBook understand it 

b) give an idea of the parent tags, the license, etc that should be
   used for particular types of applications.

I do not think that the templates should be the 'rule' - they should
only be suggestions and helpful learning devices.

As to CVS - we should regard CVS the *exact* same way it is regarded
by the developers. If, for example, Aaron *owns* the GImac-applet docs
and I want to add something to those docs - I should not just throw it
into CVS - I should contact Imac, show him what I have and ask if he
would like to incorporate them into his docs. 9 times out of 10 he
would say yes if they are good additions. With the doc-table it is
even easier to find out who *owns* what too!

CVS is not a place to change what you don't agree with. Now this is
not 'set in stone' either - if I see that Aaron spelled his name with
one A instead of two - I can guarantee he would appreciate me going
into CVS and fixing the typo. Nonetheless - I should shoot off a quick
email and say "Aaron, I fixed the typo in your name in GImac-applet -
are you sleepy or something?" 

DocBook is a strange beast sometimes - there are times when we can
find ways to display some information in more than one way - if I
prefer to use <variablelist> and Aaron prefers <itemizedlist> for a
simple list of features or whatever... fine, it brings a little bit of
the personality we both have to our docs. Thats not bad - thats the
art of writing.

As long as we communicate here and on IRC things we think should or
should not be in our documents as a whole I think it will all come out
OK - Its never easy to have a collaborative writing process - its even
harder without a full time editor who has total control - but that is
*not* how open source works or should work.


Aaron - I picked on you on purpose... you used to have blue hair :)

Cheers,

Dave

-- 

          David Mason
        Red Hat AD Labs

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




[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]