On iterative, open source documentation (or lack thereof)

AOL has put together developer.aol.com to highlight its contributions to the web community, but one of AOL’s earliest contributions, AOLserver, is silent from the list. (Yes, I did mention this to someone internally at the end of May 2006, and projects that have launched since have made it to the list, already.)

Jeremy Zawodny expresses what I’ve been trying to put into words for a while now about the difficulty of contributing previously closed source, which AOLserver was prior to 1999. The AOLserver community has always been anxious to see more of AOL’s closed source components for AOLserver get released as open source, most famously the “DCI” collection of modules which was invented as part of the AOL Digital City (now AOL CityGuide). So, what’s kept AOL from “being a better open source citizen” (if that’s really what it would mean) and releasing the DCI modules?

Jump-starting an open source community like AOLserver with a sizable and previously closed source codebase presents an interesting challenge. Most likely, the design discussions were held in face-to-face meetings, some now outdated design documents may have been created and the software was constructed under commercial pressures with all the sacrifices and trade-offs that come with them. Much of the knowledge and design rationale is primarily locked up in two artefacts: the initial developers’ brains and the produced code itself. Releasing any portion of the code alone significantly raises the bar of required understanding for participation and contribution. Making those brains available in the form of community participation (i.e., answering questions) means dedicating some non-zero percent of your most valuable asset: your people.

Contrast this with an open source community that starts from scratch, with nothing at the start. All design discussions are generally held using communication methods that are easily archivable and searchable. Even if no explicit design document artefacts are produced before software construction, a determined software design archeologist could pore over the chat logs and transcripts and mailing list archives to reconstruct the key points that drove the design using resources that are already publically available. After the documentation is started this way, the community can continue to refine and contribute to it through distributed collaboration tools, which is why I’m a big fan of Wiki software.

Is this documentation really that necessary? Again, for some people, probably not: the bar of required understanding is low enough for them. But, that set of people is quite small. There are folks at AOL who have full access to all our source code who still can’t make heads or tails of our stuff, who need serious hand-holding to make things just work. Imagine the difficulty a member of the community would have, not having access to all the code and all the people who know it well. For many, making more of our closed source code open would be next to useless to them. So, where’s the rush to open it up until all the necessary prerequisites (documentation, examples, etc.) are available?

So, given the situation, does this make AOL (or Yahoo!, or Google) poor open source citizens because it hasn’t put a license on more of its code and made it available to the community? Does it necessarily imply that the quality of the code is poor because it’s not easily open sourced? Is there a lesson about gift horse mouth inspection going on, here? I can’t speak for Yahoo! or Google, but take my word for it that the members of the AOLserver community who work at AOL have been continuing to clean up and better document more of the still-closed source AOLserver modules (like the DCI modules) with intent to eventually release them.

Tags:
AOL,
AOLserver,
open source,
Digital City,
CityGuide,
Jeremy Zawodny