Re: CVS, templates, and changes to docs

[Eric Baudais <drake x8b4e541f dhcp okstate edu>]

On Fri, 28 Apr 2000, Dan Mueth wrote:

>  
> 
> On Fri, 28 Apr 2000, Telsa Gwynne wrote:
> 
> > 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.

I think this objective should be the primary purpose of the templates.
There has to be something that has all the right markup which conforms to
all these standards we have set and will continue to set or revise in the
future.  Especially since the templates are probably more up to date than
the Handbook (not to bash the Handbook maintainers).

I also don't think the templates should be the final word on what to
include a document either.  If a writer wants to put a little history of
the app/applet in the intro or a short story or something else I'm all for
it.  It's those things that make the documentation more than just
something you read to figure out what the program does.

Looking back to getting the documentation of 1.2 together I think we
followed the templates are hardened rules on how the document should look.
I think the templates should be minimalistic to give the writer creative
freedom with the documentation.
 
> 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.

If these so called conventions exist, I think they should first be listed
and then agreed upon to follow them.  The only conventions a writer should
follow are those set in the Handbook.  I disagree with Dan that the writer
should not change "About" to "Info," if they so please.  The only
conventions that should be followed are those that we (GDP) have agreed to
follow after much discussion.  Then they should be included in the
Handbook.
 
> 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".)

I don't think the templates should be a standard to follow.  They should
only be used as a guide to new and current writers.  I think the standards
should be stated, with explanations concerning why it was done a certain
way, in the Handbook.  The templates should then reflect these standards
we might choose to establish.  I do not think the templates should be the
standard to follow.
 
> 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.

Yes, having many different panel markups looks very unprofessional.  So we
need to first, list all the things that should be standardized, if any,
second, discuss those things proposed, and third, agree to follow a
certain way of marking up or saying something.

> 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, I think you have wrongly assumed we share your opinion.

Eric Baudais

P.S. This only reflects my opinion and I am much interested in hearing
     from everyone else on this issue.