Re: sample DB_CONFIG bdb backend docs : a must in faq-o-matic

["Mark H. Wood" <mwood@IUPUI.Edu>]

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

On Sun, 6 Jun 2004, Howard Chu wrote:
> The documentation is obviously equally essential to the OpenLDAP project
> as the code itself. Why is it that you feel it's acceptable to rely on a
> small group of developers to write the code for you, but you feel it's
> OK to have your own documentation? The community knows that the code
> comes from one place. Why should the documentation be scattered all over
> the web? If the documentation you (collectively) write is useful, why
> don't you submit it back to the project, the same as a bug report or
> code patch, so that it can immediately become useful to everyone else?

Probably because it's so difficult to figure out how to do that.  If I
figure out something that I feel should've been stated in the
Administrator's Guide, my first thought is to patch the Administrator's
Guide.  But I can't, because I can't get the sources for the AG.  It takes
a real effort for me to remember that, to patch the AG, you submit a
snippet to the Faq-O-Matic and maybe someday it will be incorporated into
the AG.

> An open souce code project succeeds partially because the code is
> peer-reviewed by a large number of developers who are skilled in the art
> and/or skilled in the topic area. This helps to ensure a good quality of
> code, with no security holes or other faulty logic. Why wouldn't you
> submit your documentation to the same standard of review? Why would you
> trust documentation that was written or reviewed by people who are not
> skilled in the topic area? It makes no sense.

Notice that this applies equally to the Faq-O-Matic, which is the only
intake I know of for documentation updates other than patches to the man
pages.

> Code or documentation that's squirreled away in someone's private corner
> of the web does not benefit the OpenLDAP community. Code only benefits
> people when it makes its way into the OpenLDAP ITS, so that other
> developers can review it, revise it, and incorporate it into the main
> distribution. Why do you expect the documentation to be any different?

The documentation has a different patch submission process, even a
different submission *model*, than the code.  I'm not saying that it's
wrong, but apparently the current setup is quite different from what a lot
of people expect, so different that they fail to find the proper method
for submitting improvements to the documentation.

It's not customary that just anyone can add to a project's FAQ; typically
a FAQ has a maintainer and you email your suggestions to him.  I was
astonished to see how many instances of Faq-O-Matic there are, because
I've only ever seen one -- the OpenLDAP one.  Maybe nobody else has seen
the others either.  The only projects on that list which I recognized were
netatalk and Debian, and many others are internal or chiefly of interest
only to internal users.

The documentation and the intake for changes to the documentation are
quite distant from one another both in layout and conceptually.  I usually
have to hunt around for a while before I remember that *the OpenLDAP
Project works differently*.

Some time ago I worked out some explanations of the relationship among
OpenLDAP, SASL, and Kerberos, and wanted to contribute them to the AG, but
couldn't figure out how to do that and wound up putting them out on my own
page.  I know better now and I ought to review my writing and submit it if
it's still of any use.  But it took me a long time to understand that I
was frustrated because contributions flow into OpenLDAP in a way I wasn't
used to.

Hmmm, looking over the project pages, I see that I may still have it
wrong.  It seems that I should perhaps use the ITS for documentation as
well.  But there's nothing I can patch, so what do I do?  It would be well
to have an easily-found statement which answers the question, "how should
I fix documentation which doesn't come with the code?"

- -- 
Mark H. Wood, Lead System Programmer   mwood@IUPUI.Edu
Open-source executable:  $0.00.  Source:  $0.00  Control:  priceless!

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.3 (GNU/Linux)
Comment: pgpenvelope 2.10.2 - http://pgpenvelope.sourceforge.net/

iD8DBQFAxJFts/NR4JuTKG8RAmVsAJ98dSypIcPGekPIu+/2AFqywqapzwCfeTHZ
zJlGpF+ONt2tqqTCNta+o48=
=+OJk
-----END PGP SIGNATURE-----