Re: The GNOME Handbook of Writing Software Documentation

[lacage email enst fr (Mathieu Lacage)]

Telsa Gwynne <hobbit@aloss.ukuu.org.uk> writes:

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

I like this idea a lot.
I have found myself realizing I had missed a lot of useful tags when
writing doc and getting back to what I had allready written to remark
everything well... It's been a _real_ pain... This would allow me to
have a good idea of all the useful tags and their use quickly.

BTW: i remember the subject was brought someday but it is VERY important
that the SGML minimization should be STRONGLY FORBIDDEN for any doc.

I think that switching to XML is a not-so-far reachable goal (thanks to
conglomerate.org) and minimization is exactly the kind of thing we want
to avoid to make the switch not too painful.


> 
> Telsa
> 

regards,
Mathieu