Documentation blues

[David Shaw]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Tue, Jun 24, 2003 at 11:43:22AM -0700, Robin Lynn Frank wrote:
> On Monday 23 June 2003 06:31 pm, Ben Finney wrote:
> > On 23-Jun-2003, Robin Lynn Frank wrote:
> > > There must be some law I am unaware of that documentation must be as
> > > tedious as possible
> >
> > Does it look like this?
> >
> > Frank's Law of Documentation:
> >     Documentation is either written by programmers who are too close to
> > the program to know how to tell a user about it, or written by people
> > who had no documentation and did everything the hard way.
> 
> Pretty close!   What I was looking for was over 950 lines down in man gpg.  
> Laying every command and configuration parameter out in alphabetical order is 
> about as useful as using a dictionary to learn the spelling of a word.  You 
> might get lucky...or not.
> 
> My preference is:
> 
> "You've just installed <whatever. (or you wouldn't be reading this).
> 
> Listed below are the basic parameters you can use to configure <whatever>.
> 
> Param_1 = <something>  # this allows you to make <whatever> do <blah>
> [....]
> Param_63 thru 987 are covered in the section on advanced configuration."
> 
> And they should be in the order of need...not alphabetical.  They can even be 
> in subsections so similar features are together.

What is "order of need"?  My order of need is bound to be different
than someone elses.  Anyway, see the README file that comes with GnuPG
and/or http://www.gnupg.org/gph/en/manual.html.  That seems to be what
you are looking for.  They don't get into the more esoteric commands
though.

> Now in response to David Shaw's comment about my post about tedious
> documentation, If I knew enough about gpg to contribute to the
> documentation, I would not have needed to ask my question in the
> first place.

I don't agree with this way of thinking.  If you know enough to ask a
question, I think you are extremely close to understanding the answer.
The person who truly doesn't understand often doesn't even understand
how to ask the question.

If you ask a question, and get an answer that you understand, why not
write a paragraph on that specific detail for the manual?  If you had
to ask the question in the first place, clearly the manual didn't give
you the answer.  Once the question is answered, though, you know the
answer and could write a few lines on the subject for the next person.

I'm usually happy to answer questions, but utterly delighted to answer
them when the answer is going to be put into the documentation.  Good
documentation helps everyone.

David
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.3rc1 (GNU/Linux)
Comment: Key available at http://www.jabberwocky.com/david/keys.asc

iD8DBQE++LnG4mZch0nhy8kRAhPoAJ4xbNS6Q/YlhliGGjcI+xRM6kZr3QCgiQ3P
0WDjtECKyj00S5NUjBubRsI=
=myod
-----END PGP SIGNATURE-----