[Date Prev][Date Next] [Chronological] [Thread] [Top]

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

Agreed.

>
> 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
replication/overlays etc.

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

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

OK, thanks.

>
> -- Kurt
>
>