[Date Prev][Date Next]
RE: Odd problem with open-ldap
Please feel free to contribute documentation improvements.
At 09:12 AM 1/5/2005, Armbrust, Daniel C. wrote:
>The question and answer example was meant to be a slightly humorous view of how many e-mail exchanges typically occur when someone comes in and tries to build openldap for the first time. I spelled out some things are often implied, but not said (aka "idiot" remarks). Some of the answers I put down I believe to be perfectly correct - I just needed to put them in there to get to the end point. I was trying to point out the path that many people take when they encounter an issue with a binary - are told to upgrade - and then if they aren't an expert at building complicated software, these are the issues they may encounter.
>My point was that the two issues I brought up in my invented e-mail exchange have come up _dozens_ of times. This to me, seems like a good indicator that part of the documentation and/or examples are lacking in this area. While I agree, that the documentation shouldn't be written down to the level for a person that has never turned on a computer - and it may be hard to judge where the line is that a documenter should stop at. But when a lot of people start asking the same questions over and over again - that should be viewed as an indicator that the line was put in the wrong place for the issue at hand.
>The FAQ has _tons_ of information in it - its more of an AQ than a FAQ. Things that truly are frequently asked should be graduated up to the documentation that people are expected to read. Then, the problem is less likely to happen in the first place.
>Plus, the FAQ has answers that IMHO are poor - since they can be edited by anyone - like this: http://www.openldap.org/faq/data/cache/1158.html - Not only does it suggest using a BDB version that has since been discovered to be to buggy for use (at least that is what I have gathered from the mailing list), it recommends simply blowing away any other version of the BDB stuff on the system. The same question is answered better here: http://www.openldap.org/faq/data/cache/1113.html But then it is buried under a platform solution - even though it applies to multiple platforms.
>I don't expect people on the mailing list to thoughtfully answer every single question that is asked. I realize nobody gets paid to answer the questions. I'm just trying to suggest changes that would help more people help themselves - and not ask the question in the first place.
>My main disagreement boils down to this:
>When something is asked over and over and over again - and when "non-official" websites start popping up - that should be a pretty strong indicator that maybe part of the main documentation should be revised and improved. And I don't really consider the FAQ documentation. Documentation is what allows you to use the software properly, and not get errors. FAQs (and mailing list archives) are where you go when a problem occurs.
>My perspective on this is comparing how the OpenLDAP project operates in comparison with other opensource projects that I follow/use/workwith.