A friend of mine asked me about a piece of software that solves a simple problem : How do you share an address book in an office or home setting?
Well, most people use Exchange or something with their mail server to manage all that stuff because, generally, address book == email addresses. However, that's not always the case, and many places don't run Exchange or whatever. So how do you get/share/update addresses?
I've used LDAP for this over the years but it's consistently been a serious pain in the ass, either because of broken/stupid/bad tools, broken/stupid/bad server support, or the inherently hard to debug encoding scheme that LDAP uses from the X.500 spec. I tried OpenLDAP and it hurt. I'm sure it's better now or at least I hope it is.
Anyway, I tried looking for a SOHO solution to the address book problem and I found a bunch of pages describing, in glorious detail, how to set one up on a Linux box using OpenLDAP. Except it's very complicated; you have to worry about setting up the default schema, setting the server up correctly, so on and so forth. I'm a geek and this was a bit much for me, let alone the semi-technical friend which I'm giving this software.
Plus, this feels like using a sledgehammer when all I need is a light tap. I really just want this thing to do a few things and do them well :
- Simple user management
- Simple CRUD
- Simple backup
LDAP should provide all of this, but I've seen very few shops grow this solution themselves. Either they're a huge organization or they paid someone (IBM/SUN) to create the solution for them.
Why LDAP at all? Because every mail client and address book client I know use it. Mac, Linux, Windows. It doesn't matter, they all support LDAP in some form.
So I go to look at http://directory.apache.org because I figure, hey, it's Java + LDAP + Apache, it's gotta be at least OK to use. But I was wrong. First, there's this highly misguided screed about how directories just never got a fair shake. Let me address them in order :
- "First there is no formal education around directory technologies while several courses around relational database systems exist" - Bullshit. This is not a real reason at all. People have adopted many technologies without formal education long after they were in school or even getting training. HTTP wasn't popular when most of the guys/gals I've worked with were in school and they know how to use it well. Same with many other protocols, including IM via XMPP.
- "Developers may also fall back to using an RDBMS instead of a Directory because of a lack of rich integration tier constructs (like triggers, views and stored procedures)." This one may be partly right, but for the wrong reasons. Yes, lack of integration is a reason I, and others I've talked to, haven't used LDAP more in the software we write. But that's not because of triggers or views or stored procedures. That's because talking to, debugging, and managing the software relationship with an LDAP server is hard and very very hard to setup. There's almost always a schism between the person using the LDAP server and the person administering the LDAP server. What happens if it fails? How do you setup failover? How do you debug the connection on the wire?
- "Perhaps the most significant factor driving these faulty decisions is the lack of LDAP tooling. There are myriads of RDBMS tools for various aspects: tuning, accessing, and designing". This has some merit, but it still doesn't get at the crux of the matter, namely that LDAP is no longer Lightweight relative to the options available to developers. When is the last time anyone willingly chose to use ASN.1? Do developers even know what that is now-a-days? When was the last time a non-admin setup OpenLDAP or bothered to learn the schema structure?
Part of the reason I avoid LDAP in the software I write is that
I already have something for storing data and searching through
that data, and then I have an RDBMS as well 
I don't need Yet Another
Technology to fill this need. The world in which LDAP lives is a
fantasy world that doesn't fill more than a few needs outside of
the security realm. It could be used for more, and I
bought into LDAP when I first read about it, but several months of
pain during setup and management of an LDAP server, not to mention
the pain of client configuration and management, taught me that
there are better ways of managing this data.
LDAP isn't "hard" in the conventional sense, and it's not even "hard" to understand. It's hard to use as a tool because of arcane decisions made decades ago that have never been revisited.
But, to get to the title of this post, the biggest problem I have with Apache lately is the documentation that makes no sense and is hard to parse. I chuckled when I read "This page needs to be overworked". It's almost engrish. Ivy used to suffer from this (still does in some places) but is being improved now that it's a mainstream project.
This isn't meant to pick on non-english speaking/writing developers, but it is a growing problem with documentation on projects I want to use. It's spectacular that people are writing projects in other countries and releasing them! That's kick ass. However, it's hard to use the projects if the documentation is bad/poor/hard to read. This is true if the documentation is written in proper english (or improper english). But it seems like documentation is slowly degrading for many open source software projects.
There are a few projects that are shining examples of good documentation; projects like Spring and Hibernate. Much of the Apache Commons. But then you find projects like Directory and, well, good luck. I wanted to try and write a quick application to manage my address book, but I think I'm going to try writing it from scratch rather than use Apache DS, mainly because of the lack and quality of documentation.
I'm not suggesting that people learn english. However, it is the defacto technology language, so that should be the target eventually for a project. Still, write the documentation in the language of your choice and then ask someone to "port" it to english! At least I have a chance at using an automatic translator (or a friend who speaks your language) to get at your documentation. And maybe it'll be more complete if you write it in the language you're comfortable?
The problem has many facets, but ultimately it just makes me not want to use the software, which is pretty much the opposite of the Open Source intention.