Documentation blues

[Robin Lynn Frank]

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=
=2E =20
Laying every command and configuration parameter out in alphabetical orde=
r is=20
about as useful as using a dictionary to learn the spelling of a word.  Y=
ou=20
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>=
=2E

Param_1 =3D <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 eve=
n be=20
in subsections so similar features are together.

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


--=20
Robin Lynn Frank
Director of Operations
Paradigm-Omega, LLC
    ******
The need to do something is
inversely proportional to the
time available.