Re: GDP Stylee

[Dan Mueth <d-mueth uchicago edu>]

On Fri, 16 Jun 2000, Aaron Weber wrote:

> hey all--
> I've got a rev of the GDP handbook w/style section in it on my web page:
> http://primates.helixcode.com/~aaron/gdp.html

Aaron,

This is very good. I'm glad to see a style section in the Handbook, and
you seem to be the right person for writing it.  I do have a
couple suggestions on places we may want to put more emphasis:

1) the introduction - You mention that many people will not sit down and
read the document like a book, aside from the introduction.  Perhaps we
can elaborate on this a bit more and explain why people even sit down and
read the introduction, as this will tell us what the introduction should
contain.  I suppose a person who sits down and reads the introduction is
trying to figure out either (A) what the heck an application is, or (B)
what the main features of the application is, so the user knows whether it
is useful for doing certain tasks.  If this is correct, then the
introduction should describe generally what the application is, as well as
listing some of its main features.  It might also be appropriate to list
common uses of the application, if this is not obvious.

2) indexing - I think we may want to put more emphasis on the importance
of indexing, and its implication on document structure. Good indexing is
essential for any large or complex document.  On a system with a good
index and documentation which is logically broken into sections on topics
or tasks a user is likely to have a question on, the user can very quickly
find the information he/she is looking for.  This is much more efficient
and satisfying than trying to search the TOC or doing a search for words
in the body of the document, which is very time consuming and less likely
to work.  Since most people will be searching for information using the
index, the document must be divided into logical sections which address
certain questions the user may have, well-defined specific topics, or
tasks the user may need to do but which may not be completely obvious.

Most of the GDP members (including myself) do not have a lot of experience
in indexing, which I have heard is an art in itself.  If I recall
correctly, a person with the OSWG who has experience with indexing
suggested at GUADEC that we have just a couple people who do the indexing,
and thus become very good at it, allowing the rest of us to focus on
writing the docs themselves.  Whether we do this or not, each writer
should keep in mind that their document should be logically divided into
sections which will be indexed, and that most users will search their
document using the index.

BTW, Aaron - Feel free to work directly in CVS with this.

Dan