[Date Prev][Date Next]
[Chronological]
[Thread]
[Top]
Re: documentation updates (Was: sample DB_CONFIG bdb backend docs : a must in faq-o-matic)
At 10:46 AM 6/7/2004, Quanah Gibson-Mount wrote:
>--On Monday, June 07, 2004 9:37 AM -0700 "Kurt D. Zeilenga" <Kurt@OpenLDAP.org> wrote:
>>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.
I should have noted as well that 1) and 2) of this is echoed in:
http://www.openldap.org/faq/index.cgi?file=156
>My 2c on this is that the need addressed by web pages is often beyond the 'scope' of the OL Administrator's guide.
Certainly the OpenLDAP Admin Guide has a 'scope'. Where exceeded, there
are a number of available options. For OpenLDAP-related documents,
the project has both <http://www.openldap.org/doc/> and
<http://www.openldap.org/pub/>. The former for documents which the
project has change control over, the latter for documents whose authors
maintain change control over. For non-OpenLDAP-related documents,
well, we'll point them elsewhere.
>In addition to configuring OpenLDAP, for example, I have information on building OpenSSL, Cyrus-SASL, Heimdal, etc.
I think publishing what Stanford has done/is doing at Stanford makes
good sense. (And, if you haven't done so already, adding FAQ reference
to this would be a good thing.)
>Generally when those types of questions are sent to the OL list, the people making the inquiry are told to go and ask the related list.
Depends on the question...
I note there is a concern that by documenting non-OpenLDAP stuff on
the OpenLDAP site that we're opening ourselves up to lots of non-OpenLDAP
questions. To counter this concern, we try to include references in the
documentation to appropriate discussion forums.
>Having a 'single source' of this documentation can be a lot more useful than looking at 5 or 6 different products trying to glean the information necessary from them to get a working system going.
Of course, having 5 or 6 in-depth product documents can be a lot more useful
than having one single source document which, due to its broad scope, fails
to adequately cover the 5 or 6 products. That is, there are scope and depth
tradeoff. In the Admin Guide, we've tried to provide, in addition to specifics
about OpenLDAP Software (which augment the manual pages), an overview with
how OpenLDAP Software may be used with other systems. We try to
refer the reader to more specific documentation covering those systems for
details on how to configure them.
>I also caveat my documentation to explicitly note that it is what Stanford needs to do for its environment, and that the steps detailed may not meet the needs that others have. I think that is also a very important point.
Very much so. I'd like to others follow suit as these documents
not only serve to document what you have done, but aide others
who might want to follow your lead.
>OpenLDAP itself has a ton of features and options available to it, and how a person wants to configure and operate OpenLDAP is going to depend entirely on their needs.
>I think it would be extremely difficult to make the AG or FAQ-O-Matic address each and every environment need that is out there.
I concur.
Kurt