Documentation (Was: [OT] Too Quiet)

[Bill Campbell]

On Fri, Nov 05, 2004, Kurt Wall wrote:
>On Fri, Nov 05, 2004 at 06:39:38AM -0500, Shannon Scott took 87 lines to write:
>> I'm not sure this is helpful, but this tool will make your html
>> well-formed and prepare it for use with SAX and DOM as if it were XML.
>> I find it very handy.
>> 
>> http://tidy.sourceforge.net/
>
>HTML tidy proved to be quite useful. The issue we faced (and still face)
>at work is not that the HTML wasn't well-formed. Rather, too many different
>hands had touched the docs, so there was a marked lack of consistency in
>how some content was marked up. It was and is the lack of consistency that
>requires a lot of hand massaging.

I've been using Docbook for a couple of years, but cheat for most
relatively simple documentation.  I wrote a perl filter that
converts from groff -mm macros to docbook XML.  That way I can
continue to write documentation pretty much the same way I've
been doing it for 20+ years, and it's far easier to deal with
roff style markup than the verbosity of XML.

Bill
--
INTERNET:   bill at Celestial.COM  Bill Campbell; Celestial Software LLC
UUCP:               camco!bill  PO Box 820; 6641 E. Mercer Way
FAX:            (206) 232-9186  Mercer Island, WA 98040-0820; (206) 236-1676
URL: http://www.celestial.com/

The difference between science and the fuzzy subjects is that science
requires reasoning while those other subjects merely require scholarship.
                -- Robert Heinlein