Re: Documentation Roadmap

["Kurt D. Zeilenga" <Kurt@OpenLDAP.org>]

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.

But discussion of how to configure/use particular non-OpenLDAP
LDAP clients is certainly far beyond the scope of the Admin
Guide

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.

We do have a FAQ section titled "Integration"... where it
is considered fine to provide some discuss of other software.

>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.

>Lastly, what are your thoughts on a Wiki based system for rough TOC drafts
>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.

>Or should it be tracked on Devel FAQ and ITS for
>draft submissions?

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