The Catch-22 Of Opensource Documenation
Opensource projects tend to have a well-earned reputation for being poorly documented. Originally this was caused by the fact that most of the people who knew the codebase were developers who didn't have the skills or interest in writing the documentation. With opensource becoming more mainstream and more people getting involved I think that reason, while still having an effect, has become less of a problem. Despite that the quality of opensource documentation hasn't improved – if anything it seems to be getting worse. More and more projects don't even have half-decent reference information and just a few scraps of information on where to start.
It seems that documentation is now the way that people get paid for opensource. More and more projects are recommending one or more books instead of providing documentation for free. Perhaps having a paid form of documentation improves the quality but it doesn't matter much. There's simply not enough free documentation available to let you decide if the project actually does what you want and will meet your needs.
Not everyone who writes books about opensource is "holding out", a number of them are contributing documentation improvements back to the project, but the give away the code, sell the documentation is a disturbing trend that limits the benefits of opensource. We need to start realizing that the documentation is just as important as the code itself – if we insist on the code being free, we should expect the same of the documentation.
May 28th, 2007 at 6:45 am
Hi Adrian
Well go on then, name ‘em and shame ‘em I say (the OS projects that have rubbish documentation, or have just paid-for documentation available).
I seem to remember a developer on one OS project posting something along the lines of ‘users of OSS have *no* right to expect anything [such as documentation].’ The attitude seemed to be one of ‘caveat emptor’, which seems to me to be the wrong attitude to take, but that’s one of the realities of OSS. I’m actually struggling to think of an OS project (one that I use regularly) that doesn’t have adequate documentation… I say ‘adequate’, because the software is ‘free’, so I don’t go in expecting 100% polished, uber-comprehensive documentation. As a developer on an OS project I can say that writing the documentation is not a task that brings one a lot of glory (any glory actually – in fact, one often gets ribbed for taking some time out to write some documentation), so it’s no wonder that it comes low in the priority list of things to do in an evening after one’s paid day job.
One important part of documentation that you didn’t mention was forums… yeah, not strictly documentation, but if the forums are lively enough they can be an excellent resource, full of tips and stuff that ain’t in the main documentation for one reason or another (space, focus, etc.). Over time they do become a documentation resource (of sorts), and (speaking personally) whenever I see something cool on the Spring forums that deserves to be in the Spring documentation, I go off and add it.
I’ll enter into the spirit of naming and shaming to start you off, and rip into the Spring documentation :)
I don’t think the Spring documentation is too bad (I am trying to be unbiased); however, it does suffer from not being very well organised, there are no tutorials per se, and there are to date no hardcopy books devoted to coverage of Spring 2… basically, as it stands right now, if it ain’t in the Spring documentation then it ain’t anywhere. As to what is being done to remedy this, as regards the Spring documentation, I’m aware of it’s shortcomings (mmm, not much else happening there though), and there are other folks out there who are writing Spring 2.0+ books (Craig Walls for example).
http://www.manning.com/walls3/
I’d be interested to hear what OS projects folks rate as having rank, Stoke, Trent, and otherwise rubbish docco :)
Cheers
Rick
May 28th, 2007 at 7:15 am
Rick,
Struts 2 is the main source of frustration for me, but the other project that kicked me over to this rant was hibernate. Not so much that it’s documentation is completely useless, but instead of the website pointing you to the docs, it recommends you go and buy an e-book instead. Hopefully there is good documentation in there somewhere but it was just another data point of docs being a paid extra instead of the enabling feature that makes the code useful.
May 28th, 2007 at 6:28 pm
Hi Adrian
I daresay you already know about this resource, but for those readers of your blog that might not, InfoQ has a new book devoted to Struts2.
http://www.infoq.com/minibooks/starting-struts2
I take your point about paid-for-docco though, cheers
Rick
May 28th, 2007 at 7:04 pm
Rick,
Yeah someone pointed that out on the last post. It gives a good architectural overview but unfortunately it’s not a reference which is what I desperately need right now.