[Date Prev][Date Next]
Re: Documentation Roadmap
<quote who="Kurt D. Zeilenga">
> At 01:09 PM 12/3/2006, Gavin Henry wrote:
>>> and, more importantly, whether we want to produce and maintain one.
>>This has been bugging me. I think we leave all the other projects to
>>provide integration docs.
> With LDAP clients, generally, yes. Our documents do however discuss
> slapd(8) integration with Berkeley DB, OpenSSL, Cyrus SASL, Kerberos,
> etc.. Of course, it's generally appropriate to assume the reader
> is familiar with these packages. That is, we do try to avoid
> duplication of documentation.
Maybe we have links to their docs in the appropriate sections, and pull in
some of the compiling FAQ entries for linking, as that *always* comes up
on the list.
> But discussion of how to configure/use particular non-OpenLDAP
> LDAP clients is certainly far beyond the scope of the Admin
> All client examples use OpenLDAP command line tools because a)
> these are the only clients we can assume the admin has,
> we need document our command line tools, and it should be
> relatively straight forward to translate use of OpenLDAP
> command line tools to other tools.
Yes, although some don't grasp that.
> We do have a FAQ section titled "Integration"... where it
> is considered fine to provide some discuss of other software.
Aye, I think that should stay in the FAQ, linked to from the Guide, as
it's too fluid to create static docs for.
>>How about a Deployment guide instead, or would
>>that fall under the Admin guide? The Deployment Guide could have real
>>world cases etc. in it and the tuning/monitoring section.
> Deployment of slapd(8), yes. Deployment of some particular
> non-OpenLDAP software product, no. The information in the
> admin guide should be generic, something which most everyone
> can understand and make use of. Discussing slapd(8) administration
> in terms of "white pages" is good because "white pages" is a
> directory application that is simple in concept but also teases
> out numerous directory service issues including authorization,
> schema administration, tuning/monitoring, etc... and we can
> generalize LDAP client issues.
That's what I meant, deployment of slapd only, with real examples of
>>Lastly, what are your thoughts on a Wiki based system for rough TOC
>>etc. for new authors?
> That's how I treat the FAQ... In fact, one of large documentation
> TODOs should be adapt various FAQ into Admin Guide chapters.
> For instance, much of the FAQ authorization answers should be
> moved into the guide.
Yeah, I've pulled in all the Performance and tuning stuff last night into
tuning.sdf, just got to organise it properly. Then I was going to go
through the over entries.
>>Or should it be tracked on Devel FAQ and ITS for
> Actual proposed changes to the Admin Guide, manual pages, and
> other documentation distributed as part of OpenLDAP Software
> are the same as OpenLDAP Software code. A patch against the
> source should be submitted to the ITS system.
> -- Kurt