Planting a Tree

This morning I was rolling through my blog feeds, catching up the latest news in the world o' Linux, when I noted an interesting piece of artwork in Celeste Lyn Paul's obso1337.org blog.

The topic of the blog entry was User-Centered Design, related to Paul's participation at Akademy 2008. If you groove to design, you should read the entry for that sake alone. What intriqued me about the figure (which is a pretty good summary of the state of software design) was not the overall point it was trying to make, but specifically the lower-left panel on documentation.

The panel struck me because, while funny, it's also very true. The state of documentation, particularly around Linux, is pretty invisible. And yet no one can really explain why.

The most common answer I get is that developers don't have time to document--they're too busy moving on to the next problem. A variant of that rationale that I frequently hear is "the source code is open, just look at it." I'm not even a developer by trade and even I know how scary that statement could be. Another oldie but goodie: "I don't need documentation, so why should I waste time making it for someone else?"

What's ironic about all of these rationales is that they all run along one, central theme that's an anathema to free and open source development: it's all about me. I don't need it, I don't have time, I can't be bothered. Not exactly the caring and sharing we've come to expect.

But as a non-developer with his own set of skills, I can also appreciate that developers did not really sign up to be documentarians when they started hacking code, so while I think more effort could be made by a lot of folks, I don't think its constructive to harshly condemn people for not doing the tasks they never wanted to do in the first place.

Plus, let's face it, putting together documentation isn't exactly the easiest thing in the world to do. Even those who are inclined to write something up need to figure out what they're going to write (specs, end-user documentation), what format they're going to write it in (HTML, ODF, Docbook), and then where they're going to put it (the project page, The Linux Documentation Project, SourceForge). And don't get me started on languages. You could make an argument that the lingua franca of open source is English, but there's a whole passel of non-English speaking developers out there who would likely disagree.

Documentation should not be this hard to figure out. You set up a repository, pull existing documentation in, then invite others to update old documents and contribute new. You don't set up a lot of rules for contributor's formatting, so that you keep it easier for the writers. Instead, you put more work on a strong editorial team that handles formatting and indexing. Get things consistent and looking good, so everything has a good look and feel.

Doing such things, however, takes a lot of work, especially on the part of the editorial team. I have watched TLDP grow and shrink in fits and starts over the last decade exactly because it is such a hard thing to manage. Will all respect to them, the TLDP team has done a great job over the years, but I am wondering if there's something more that can be done.

Over the coming weeks, we will begin to host developer-oriented documentation from a variety of vendors and developers, slowly building that repository I was talking about earlier. We already have relationships in place, and the sources of knowledge I've spoken with already are set to go.

As that is going on, we will be exploring new paths to connect to documentation. I am extending an open invitation to any interested projects to begin working on documentation. LDN will be a central respository of articles, howtos, and links to outside information, and we may as well get started now.

It's going to start small... like a seed in that picture above. Plant the seed on that empty grassy field, and let's see if we can get a tree of knowledge growing.