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

Re: logging

Joseph Dickson wrote: 
A quick preface -- I appreciate the work that everyone puts forth on the
OpenLDAP project, including the documentation.  OpenLDAP does a great
job of allowing me to spend my time on things that are interesting and
important to my particular situation, rather than fighting with a server.

However, I do tend to speak up when I hear folks talk about the
documentation that exists as being adequate... I think the best evidence
that this is not the case is that, on this list, I consistently see the
same 4 or 5 people answering the questions which pertain to the OpenLDAP
server itself.

I don't think that proves your point; the vast majority of people using OpenLDAP already figured out how to do everything they want with it and never come here in the first place. All you're seeing is that a small segment of the population actually takes the pains to answer questions.

I would suggest that at least keeping a recent version of the
documentation on the project website would help a great deal.  I don't
agree that the best place for the documentation to live is with the
code, at least not for the user.

With 2.4 we've put procedures in place to update the online docs whenever a new release is uploaded. As for docs living with the code - if you're using a prebuilt distro, the docs obviously live wherever the distro packager put them. If you built it yourself, the docs get installed when you install the binaries. I don't see your point.

When you're looking for a software feature, the manpages and Admin
Guide should be your first resort. Pretty much every feature is
documented. Some features exist that are undocumented; most of them
are intentionally so, so don't give them a second thought. A web
search should be your last resort.


Could you give me an example of a feature that remains undocumented
intentionally?


NO.


(just kidding)

This seems like a bad philosophy on the face of it, so I
must be missing something..

Ok, for example, there are various options in different sections of code that can only be enabled by explicitly defining certain macros at compile time. They're not documented anywhere; if you look in the source code they're obvious though. These tend to be extra debug functions that developers can use while working on related code. Most people will never need them; developers who need them can use them easily enough.

In general, I just wanted to remind everyone that OpenLDAP's
documentation isn't great, and saying that it is doesn't really help.
Compare to the documentation of other projects (for example, Postgres),
I think we can agree that there's quite a bit of room for improvement.
I know it would be better for me to step up and begin writing rather
than rubbing salt in the wound, as it were, but sadly my free time is
already devoted to other things so the best I can do at this point is
try to remind people that there is work to be done on the documentation.

Your reminder is less than worthless, because it just gives people an excuse to continue to not rely on the existing docs, instead of using them and helping to fix their shortcomings. It also fails to acknowledge the tremendous amount of work that continues to be done on actually improving the docs. (E.g., the 2.4 Admin Guide which is over 100 pages longer than the 2.3 Guide.) And it belabors the obvious - everybody actually contributing to the OpenLDAP codebase is already keenly aware of the need for improvement. If they thought the status quo was fine, they wouldn't be writing contributions in the first place.
--
-- Howard Chu
Chief Architect, Symas Corp. http://www.symas.com
Director, Highland Sun http://highlandsun.com/hyc/
Chief Architect, OpenLDAP http://www.openldap.org/project/