Re: The GNOME Handbook of Writing Software Documentation

[Telsa Gwynne <hobbit aloss ukuu org uk>]

On Sun, Jan 30, 2000 at 09:16:13PM -0600 or thereabouts, Dan Mueth wrote:
> 
> This weekend I started the GNOME Handbook of Writing Software

...and nearly finished :)

> Documentation in CVS at gnome-docu/gdp/gdp-handbook.sgml.  I also put it
> on the web at http://www.gnome.org/gdp/gdp-handbook/.  

> Note that one section, "GDP Documentation Conventions" is meant to hold
> all the numerous conventions the GDP decides upon, such as use of section
> tags, formatting, use of SGML minimizations, etc. Presumably we can fill
> this section in just by going through the mailing list archives.

I think this is a really good idea.

> Basics of Documentation Style - Any good writers among us who can tell us
> all how to be good writers?

I've seen some good resources recommended by technical writers; I'll
dig 'em out of my bookmarks. 
 
> Telsa will be adding a section explaining how to write good DocBook.

Haha. Let's clarify that a little :) Telsa will be adding a bit
with a section with lots of words and concepts which can be marked up,
and then have it marked up in bits, so that the first bit has all
the screen markup stuff, another has all the "referring to other
docs, sites, people" stuff, etc, and then the last one with the
lot of them. The idea is that basically, I discovered I wasn't the
only one who'd look at something and think, "I know there's a tag
for this", and then have to hunt through about 300 tags, many of
which were irrelevant. Grouping them together into clumps means
someone can think, "this is a tag about a quote", look for the
relevant section and find an example of the minimal details you
need (like, say, <blockquote>Blah blah </blockquote>) and hopefully
an example of it with all the optional bits in (like, say
<blockquote><title>Kubla Khan</title><attribution>Coleridge</attribution>
In Xanadu...</blockquote> -- I'm picking this because it confused me 
no end that many things are <tag id="something"> and this one is 
<tag><other tag>foo</other tag><nother tag>poo</nother tag> without
anything in quotes :))

This is pre-coffee so not making sense. Basically, when you have
a paragraph with about twenty different things being used in it,
it's hard to winnow out the example you want, but if you have four
versions of the same one marked up partially and then a final
version with all the markup integrated together, perhaps it will
be clearer what fitted where.

Then again, maybe not.

Telsa