Re: CVS, templates, and changes to docs

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

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


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



No I disagree here. You are assuming that all apps will have that
menubar. But not only that but you assume that a menubar will look the
same across the board. Well - there is no UI guide for hackers and
there is no telling if your menubar will have a View menu or not.

This is one thing that should be in the handbook! The template should
not serve as a method to tell people how to mark up a menubar - it
should help people with the things they will *always* need as well as
help the newbie see how a DocBook document begins and ends. Period.



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


Those are all nice but if we fill the template with everything that
you can conceivably need in a document the thing will be unreadable at
best. Keep in mind - not everyone uses an editor that is colorizing
comments - they are not always easy to read. If people start going
astray in their docs I think it is all of *our* jobs to point it out
to the person and reference the section in the Handbook on how to do
whatever it is they are doing. That is the *purpose* of the handbook.


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


Well I don't think this statement goes very far. Some code is complete
crap so lets not go there. What I'm saying here is that this is all a
very new style of producing docs in the grand scheme of things and
I've no doubt we can make it work as well. But we have to remember
that we are in some really cool territory here in the 'history' of
technical writing.... this sort of thing has no complete
handbook... yet :)


Cheers,

Dave

-- 

          David Mason
        Red Hat AD Labs

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