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
<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
-
Gavin Henry -
Kurt D. Zeilenga