Great product ! now, about documentation ..

[metalrules]

I'd just like to leave a comment about my experience using the Spring-LDAP APIs. I've recently needed to provide a set of extracts from an LDAP database, in limited time (as always..). I only have basic knowledge of LDAP, and haven't used Spring before.

I have however used the 'traditional' LDAP APIs previously, and there is just no comparison. The Spring API is levels of magnitude better. At least for what I did anyway. I needed a fraction of the code, and the code I did need to write was much cleaner.

I do have a beef with the Reference Documentation however. I suspect there are a many, many people around who are not LDAP experts (or Spring, yet), but need to get a basic LDAP program up and running. The Spring-LDAP reference document could of been written with those people in mind. For instance, give a COMPLETE example of using the Spring LDAP API as the first example (if possible not using inner classes), including any related XML. It's just not true what's been written : "we get exactly the same functionality with the following code:" .. the extra, required XML is belatedly put at the bottom of the page ! Sure, this is a small point, but when you are trying to get something up and running, you don't want to be sifting thru different sections of a document trying to put it all together.

Also, make sure all example code compiles. If I recall, Example 2.2 didn't compile, I think I needed to change it.

And what a pity you don't explicitly discuss the handling of repeating attributes, in effect making the initial example using "AttributesMapper" irrelevant in anything but the simplest LDAP implementation.

Personally, I think it's a bit lazy to give a reference to an internet article in formal documentation, to explain the software. In this case the problem is compounded because the article mentioned has the same faults as here (particularly, assumed knowledge of Spring).

Most programmers using open source software are well aware the documentation is usually patchy. Like Spring, I'm sure much of it is written by very clever people, to whom documentation is a bit of an annoying afterthought. In the case of Spring however, I'm being particularly critical because it's backed up by a professional company in Interface21. Also, the software is so dammed good it would be such a pity to see it sink because of poor doco...

[ulsa]

We appreciate you taking the time to comment on the documentation. If you have specific fixes to contribute, like a typo or a missing bracket, you can create a JIRA issue here (http://opensource.atlassian.com/projects/spring/browse/LDAP). One other guy did just that, which made it very easy for me to fix those issues.

You say you are not used to Spring and find the documentation on a level that assumes too much Spring knowledge. That's something we have struggled with. It's always difficult to choose a level that suits most potential readers. In our case, we simply assumed that the reader would have both some LDAP knowledge and some Spring experience.

You assume that we consider documentation "as an annoying afterthought". We don't. We take documentation seriously, but it's hard to write reference documentation and this is the first time we get any significant feedback on it.

Again, thanks for your comments.

[metalrules]

Thanks for replying ulsa. I more than agree with you - writing good reference documentation is in fact very hard indeed. Good to hear the String team take doco seriously, the fact you've made an effort to even write a reference document is great. The reason I posted was because a quite experienced Java (but not Spring) programmer I know also had problems getting up and running. Got me thinking others may of had the same experience. Not everyone is going to report it took them some effort to get what is really such a nice, simple API to work...

I know I sound critical of the doco, but to me it's really only a few things you need to consider to really improve it. For instance, you've said it's difficult to pitch it at a level for readers without Spring. Well, really, you just need to make it clear what that there's some config xml required (ie, do a complete working example), and what bits of that xml may need to be changed. Anyone curious about Spring can take it from there.

I checked Jira, and the compile problem I mentioned has already been reported (Jira key LDAP-40). Thanks again for your reply