> I've often thought about this, as Samba do similar at:
>
http://wiki.samba.org/index.php/Main_Page as do other major OSS projects.
But, then if we look at a page relevant to *this* project, you get something
like:
http://wiki.samba.org/index.php/Samba_%26_LDAP#Setting_up_PAM_and_NSS_to_...
Which is incomplete, misleading, and wrong on all distributions but SUSE.
Or, you follow links on some of the other resources that have been posted in
this thread, and you get something like this:
http://fedoranews.org/mediawiki/index.php/How_to_setup_and_maintain_OpenL...
or this part:
http://fedoranews.org/mediawiki/index.php/How_to_setup_and_maintain_OpenL...
And, they missed the usual advice of editing migrate_common.ph (instead of the
easier method of setting the LDAP_BASEDN environment variable), by only using
the dc=example,dc=com example, thus ensuring all other users will be confused
later:
http://fedoranews.org/mediawiki/index.php/How_to_setup_and_maintain_OpenL...
Appreciated comments, but these projects *never* come to us and ask us
to review anything. Are we expected to spend all our time reviewing and
editing others work?
> Here are the issues with your appreciated suggestions:
>
> 1. The OpenLDAP project do not support 3rd Party software
While I don't have a problem with this, the question is why should this
prevent OpenLDAP project documentation (with suitable disclaimers) from
covering how to allow OpenLDAP to support other LDAP client software.
But how many times do we need to cover it? No matter what client or
software using a Directory, it's always the same; custom schema (give or
take), relevant indexes and ACLs etc. Another client, another day.
For
example, the only documentation available for configuring Solaris for using
LDAP for user/group accounts assumes you use JES LDAP. Sun certainly isn't
going to write any, and I would like to put the details somewhere before I
forget them.
But isn't that the duty of the authors of said software that provide
this functionality.
No, we have a perfectly good FAQ. You could add a new item in client
integration.
> 2. We have to find the time to mentor and verify the howto/wiki
> contributors.
Are you saying I need mentorship and verification?
Yes, everyone does. Mentoring could mean instructing you how to author
using the SDF tools, or wiki syntax etc. If someone thinks they never
need help or clarification sometimes, then they must be very arrogant.
> 3. We have to find the time to fight the wiki spam
Not if you limit contributions to authenticated users. And there is the LDAP
authentication plugin for mediawiki ...
Yes, we could do invite only or get a new contributor to justify their
addition. But again, we have a great FAQ system for this.
> 4. We have to find the time to keep the howtos updated
As the scratchpad wiki proves, I don't have *much* time ... but if a few
people can spare a small amount of time, it may be viable.
We all seem to think we don't have a system in place for this, namely
the FAQ. I've only mentioned a wiki, as people are talking about it.
We've had the FAQ for years and years now, but people are still shy.
> 5. Resources, lack of resources, need more resources.
> 6. etc.....
>
> *My* first and foremost priority is to finish the Admin Guide, keep it
> accurate and up to date.
>
> I think, as we have done all along, we leave the 3rd party integration
> to the 3rd party projects (like the wiki mentioned above).
Which obviously isn't doing such a great job. And, why should we leave it to
Samba to document how to set up nss_ldap and OpenLDAP optimally? Or, is this
an area nss_ldap should cover (including the indexes, ACLs etc. that should
be configured on the server side)?
I'm confused here. We should step back and think about the community.
Does the normal Open Source community author a piece of software, then
document every possible integration scenario? Should the Linux Kernel
team provide me with a guide how to install my graphics card that sits
on top of it? No, they provide docs for the author of the card drivers,
who then give me the install guide. Just like Samba, because LDAP is an
integral part of it.
> What we don't
> want is a wiki where people come along and start posting How tos that we
> don't have time to vet, which in turn starts to dilute the OpenLDAP
> quality brand and take our time away with the little resources we have.
It may be better than having hundreds of howtos out there in random places of
much worse quality, leaving the impression that the OpenLDAP project prefers
this to one authoritative place, where at least contributors or experts can
correct mistakes (which we can't do for all the broken howtos).
Possibly.
> However, what is *vital* is that we provide a means to put the Admin
> Guide sections into working configuration examples (which some sections
> have/will have). This could mean real world deployment examples etc.
But, if we can't cover nss_ldap, Solaris ldapclient, sudo, proftpd,bind,
dhcpd, autofs, samba,apache-mod_vhost_ldap, freeradius, kmail, evolution,
thunderbird (all of which I have used with OpenLDAP), what do we cover (that
isn't covered in man pages)?
Sigh...Administration of OpenLDAP perhaps?
> It's all very good having in depth guides, but sometimes it's better to
> get something running and come back to the main docs. The vessel in
> which we present these complete examples is irrelevant and can be
> decided at any point.
>
> So, coming back to your wonderful offer of help. If you would like to
> look at the latest docs in our source repo and pick up a
> section/subsection that appeals to you, we can move towards a complete
> and detailed OpenLDAP 2.4 Admin Guide and then do the wiki/howto stuff.
>
> Does that sound like a plan?
IMHO, it is more important to have concise, clear, documentation on getting
the basics most people need to get started with (before they can justify
spending more time to learn the ins and outs of all the features) with the
most gain for the least effort, than documenting all the overlays, or the
backends that are not used frequently.
Which the quick start does. We aren't an LDAP training centre.
I leave the last part above for others to discuss.
--
Kind Regards,
Gavin Henry.
OpenLDAP Engineering Team.
E ghenry(a)OpenLDAP.org
Community developed LDAP software.
http://www.openldap.org/project/