For whatever reasons people who can write don't work for free software
projects. The whole FOSS movement is hindered by the fact that
documentation isn't that great.
/Thomas
IMHO it's definitely true that it holds a lot of OSS stuff back,
especially the lack of coherent developer documentation and
properly-commented examples.
I think it's a symptom of the mindset with a lot of people who devote time
to OSS, which is basically (and quite rightly) that, since they're giving
their time they're going to spend it on the interesting stuff. In the
projects I participate in, as well as those I run, I consistently find it
most difficult to get people to document even the features they add, let
alone help document existing stuff. So you get gems like:
/**
* get the register
*
* @param registerIndex the register index
*
* @return The register
*
* @throws SomeException on error
*/
public Register getRegister(registerIndex) throws SomeException {
return registers.get(registerIndex);
}
It's like the whole 'start at 1.0' thing, when writing the software
doesn't even get you halfway there in the real world. I'm fortunate I
suppose in that I find it very easy to document, but generally the fashion
is to do the interesting stuff, leave the tweening to someone else, and
declare anything you don't have time or inclination to provide as
'useless' or 'retarded', or (more common than you think) invent a new
AntiPatternWikiWord to describe it (as in ProvideUserDocumentation,
AssumeUserIsNotClairvoyant, and ExpectConsistentUseOfCollectionsOrArrays).
In my own stuff, once past the drastic-changes phase, I always try to make
sure theres plenty of documentation, but more importantly that it's clear,
relevant documentation (e.g. Javadoc for contracts, the most general usage
information at most one click on the website, etc) but it can be a losing
battle sometimes. Believe it or not, some FOSS projects don't even _want_
documentation, and many of those that do don't understand the difference
between documentation and advertising.
