Hi guys,

I know that there's a lot of flux now in the code and that makes certain initiatives a moving target when it comes to documentation. When you actually finish writing the documentation the subsystem you are documenting might have made a full 180 degree turn in direction. I'm frustrated with most of you as well in this area. It's phenomenon we are going to struggle with unfortunately as we build and change things aggressively in some areas. But in general we're very good here in Directory dealing with documentation and tests when you look at some other projects. Just take a look at some of the Hadoop related sub projects and you'll know exactly what I mean. There's even no internal documentation even.

However there are some areas that have been rather stable over years changing very slowly. Some critical aspects like the search algorithm don't change as much since big divergences can cause big head aches. In these areas we can keep documentation in sync. There have been a set of changes in the recent past with respect to the removal of the NDN and UPDN indices with RDN index introduction first, and now we've changed xdbm to use the RDN index for hierarchy management. Also the new RDN index is a bit different in the way it handles keys and values: it's a composite index effectively. This can be hard for new comers to grasp especially when the documentation is not synchronized. This is not the most straight forward topic in the server but it's by far the most critical part.

Even if we cannot make fancy documentation we should at least reference emails or X-OUT things that no longer hold to give people a cue about have things have changed. Now that I'm involved with the university system I've met several people that have given me this feedback and I wanted to share this on list. Incidentally because of this new university involvement I've had to deal with settling in but that gives me more of an opportunity to get at least you guys some fresh recruits :). Having good documentation in the key areas will make it easier for us to grow the community more without having to do too much hand holding. It's hard enough to find the time to work ourselves, it would be more of a shame to have to repeated have discussions on list about documentation addenda for each new comer.

With that said, if those those that make these new advances in the XDBM design can at least annotate the existing documentation that would be great. Nothing fancy is needed for now but if the right cues and verbiage can be added that would be great step. Later on I want to break out OmniGraffle and/or yEd to pretty up the design/dev docs and make it easier to digest. 

-- Alex