The Buckblog

Let it never be said that Jamis Buck is not a staunch supporter of the opensource movement. I am not only a believer in it, I am also a contributor to it.

That said, let me just whine and complain for a moment regarding what I see as one of the biggest weaknesses of the opensource community.

To begin: at work I am trying to learn how to use (among several other Java technologies) the Maven build system. Everything I’ve read and heard about it says it is pretty whiz-bang and life changing.

My experiences have not been anywhere near as positive as they should have been, if I am to believe all the propoganda I’ve read about it. Instead, I’ve spent many fruitless hours trying to weed through lousy documentation.

And that’s where the opensource community really needs to improve. Developers (and I can say this, since I am one) tend to write lousy documentation. That’s not always because they can’t write, but rather because they can’t easily step outside of what they are working on and write from an outsider’s perspective.

For example, all of the Maven documentation that I’ve read has, at its root, the implicit assumption that you already understand why Maven is important, and what it takes to make it work. Even the parts that are intended to help you get Maven working in your first project seem to assume that a 200-line project.xml file won’t faze you in the least.

It fazed me.

In fact, it fazed me so badly that I began doubting the veracity of the documentation. "Is this really necessary?" I wondered. "Am I missing some crucial point that is covered in another document?"

Alas, no. Maven requires every project to have a project.xml file, chock full of obfuscated tags and obscure data elements. Why? To make your project easier to understand. Ha!

Needless to say, I’m a bit discouraged. If only, if only...

If only opensource software developers could find some good way of writing documentation, and writing it earlier instead of later...