[Date Prev][Date Next]
[Chronological]
[Thread]
[Top]
documentation updates (Was: sample DB_CONFIG bdb backend docs : a must in faq-o-matic)
Let me clarify a few things.
1) the source for the AG is available in CVS, see:
http://www.openldap.org/software/repo.html
http://www.openldap.org/devel/cvsweb.cgi
2) changes to the AG are be submitted and treated same
as changes to code, see:
http://www.openldap.org/devel/contributing.html
3) FAQ is independent of the AG, changes to it are submitted
directly to it. The FAQ is often used as a breeding ground
for future AG submissions, but the FAQ itself is NOT a
AG submission mechanism (nor is a prior FAQ submission
required to make a AG submission).
And if you or others feel that the webpages don't reflect this,
please feel free to submit changes to webpages. This should
be done through the ITS system as well. Source for the webpages
is actually in CVS as well, but this is not documented. So,
normally, changes to webpages are submitted in a descriptive
form.
Kurt
At 09:01 AM 6/7/2004, Mark H. Wood wrote:
>-----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-----