directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Alex Karasulu <akaras...@apache.org>
Subject [Documentation] Updates to at least synchronize with slow changing key topics
Date Fri, 26 Aug 2011 15:25:47 GMT
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.

Thanks,
-- Alex

Mime
View raw message