Re: Help Docs

[Michael Poole <poole graviton res cmu edu>]

John R Sheets <dusk@smsi-roman.com> writes:

> Maybe what we need is a help-writer app that makes it insanely
> easy to create good DocBook help docs, something that you could
> just open up and start typing.  Does something like this already
> exist?  I must admit that I haven't looked into this yet (my own
> GNOME app is currently in version 0.0.0, so I won't need to think
> about this for awhile).  From what I've heard, DocBook is a great
> format, but very hard/slow to learn.
> 
> Point being, the easier it is for programmers to whip together
> meaningful documentation, the more likely it will be that they
> will do so, and even do a good job at it.

    As a coder and someone who has written some amount of documentation
in DocBook (about 1000 lines), [X]Emacs+PSGML is a pretty useful tool
if you point it at the DocBook DTD.  It certainly cuts down on the
learning time -- you can see the valid tags at any point and insert
one easily, and it knows the valid attributes for any tag -- so after
a bit of learning about which tags should be used for what, I spent a
much larger amount of time deciding what I wanted to say and how to
phrase it than dealing with DocBook.  The fraction of (unproductive)
wrangling-with-unfamiliar-language time went way down as I wrote more
docs.

-- Michael