Help Docs

[John R Sheets <dusk smsi-roman com>]

Chris Jantzen wrote:
> 
> John R Sheets writes:
>  >  It is more important to have GNOME in a solid, well-documented
>  > state, than it is to play PR games with programmers (of which, I am
>  > one, so I'm slipping my own neck into the noose, too).
> 
> My gosh! The voice of reason! That's three out of four or five coders
> I know on this list who agree that documentation is a high
> priority... You non-coders paying attention?

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.

We should also at some point create some standard Help doc
templates so that writing a help system becomes more a
fill-in-the-blank operation than another full
design-write-rewrite cycle (i.e. less debugging on the help
docs).  This will also lead to a more universal help style that
will make life easier for users too.

Should the conceptual organization & structure of the help
documents be a (lower priority) part of the style guide?

John