Saturday, September 22, 2007

Code Literature

Open source projects documentation is a touchy subject.

I know it first hand from my own experience with NxBRE: writing and maintaining the 55+ pages PDF guide is not only a significant effort, but one of a very different nature than the effort of developing the product itself.

The wiki-based knowledge base is a good alternative: less formal, built from users questions and easy to maintain, it is definitively a viable approach for documenting small scale projects like mine.

This is also something learned on the field, as I have to work a lot with open source solutions. A pristine and up to date documentation is still an exception, at least for non-company backed projects. After hours of trial and error, fighting with an on-line documentation that was sometimes outdated (many examples would simply not work) and sometimes too advanced (showing features available in snapshot builds only), I came to consider recommending a paid-for solution, just for the sake of having someone to blame if the documentation was bad.

But that would have been too easy to surrender that way! Instead, I reverted to the more courageous tactics of the open source addict:
  • explore the provided running examples,
  • if not enough, browse the test cases,
  • if still not enough, trace debug with the source code attached to the IDE.
Except for company backed projects, you have got to get ready to do this when opting for open source. In fact, the presence of running samples, a wealth of unit tests and human readable source code are important decision factors to consider when selecting an open source solution. After all, the ultimate truth is in the code, all the rest being literature.