Re: Documentation templates and references

[Telsa Gwynne <hobbit aloss ukuu org uk>]

On Tue, Jan 25, 2000 at 10:19:47AM -0600 or thereabouts, Dan Mueth wrote:
> 
> Does the GDP have documentation templates for the various types of docs
> that accompany an application?  After reading sasha's suggestions and

No. Dave (? -- someone, anyway :)) and I were talking about this on
the docs channel the other day. I had been admiring the FreeBSD's
folks' templates and thinking that the only way I ever got started
with DocBook was to take someone else's (at least I had the sense
to start with a GNOME one to get the same format!) and just mangle
it. I made myself my own little template for future reference and
was contemplating bulking it out and seeing whether it was any use
to anyone.

> We could just say that the documentation for application X is good and can
> be used as a template, but I don't think this would give us the
> flexibility to provide a short, yet complete template illustrating all the
> various markup tags and nomenclature (eg: GNOME, not Gnome) GDP authors
> should use.
> 
> Perhaps we should have (1) a simple template with just the basic tags
> which people use most, and then (2) a more complete GDP reference document
> which lists the proper markups, nomenclature, etc.

Sasha volunteered before me. I nominate him to do it :) (Also, I think 
he knows more about DocBook. :) Like exciting things like entities
and stuff. And I keep finding more tags I could have used, too, and
having to go back and add them.)

What I thought would be handy is a sample article and a sample
book chapter, with the correct GNOME DTD wotsit at the top, and the
boilerplate at the start about authors, and then separate sections
on "Different sorts of lists and when to use them. All the words
and concepts you _could_ mark up _with_ _examples_" and so on. 
The DocBook book is great for definitions, but I find it poor on 
examples of "you have this word and concept and there are two tags 
that might apply. Which is the one to use?"

Telsa