Re: Documentation templates and references

[Gregory Leblanc <gleblanc cu-portland edu>]

Telsa Gwynne wrote:
> 
> 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.

I haven't looked around the FreeBSD site, but I'll do that later.  Do
they have anything to go along with the templates, or are they just
templates?  I'm thinking like some documents that outlike the
conventions and proper language style things, although these could be
the "content" of the templates, I suppose.  I for one would like to take
a look at what you've got for purely self-serving reasons.

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

Everybody seems to have this idea for the doc projects, but I haven't
seen anybody write one yet.  I've tried a couple of times, but I don't
seem to have a good enough knowledge of DocBook to do the technical
side, and I'm not clear enough on the best documentation conventions to
create that part of it.  If Sasha will volunteer, so much the better! 
:)

> 
> 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?"

I think that's technically an "identifier", but whatever.  Well, if it's
not inline markup, use both?  I'm not too clear on when I should use
certain tags either, but I'm sure that Norm has a pretty good idea.  :) 
If we give plenty of examples, and if all of the GDP docs are "model
docs" within reason, then there should be plenty for people to work
from.  
	Greg