Hi all,
I thought I'd post some further info in support of Roberto's idea of a code-freeze for documentation.
(Ok Don, lets call it a code freeze, with the exception of critical developments ;)
I still feel this idea is a good one, and I still think Roberto is right that if we don't address it now it'll never really get solved.
Just from the 'philosophical' perspective. We'd all agree that a serious bug is one which stops users/developers from using a package.
Therefore if the supporting documentation is sufficiently poor (or just plain missing Tut Tut), then surely that stops a whole raft of people (newer users in particuar) from using a package?
I therefore argue that poor documentation *is* a serious, release stopping bug....
But this is not just my opinion. As testing has begun I am getting contacted by many testers, all with exactly the same problem!
I can't figure out what this package should do because there is no/little/poor documentation.
I would of course like to write to each of them and explain how it works and so on.... but there are only 24hrs in a day ;)
The feedback I've had from almost all testers is that the documentation is not good enough, and is severely hampering their ability to test..
I suggest thats a pretty bad (and persuasive) situation.
Ok, even if we don't agree on a freeze (and I still think short-sharp-shock is the way to go) then can we at least agree that in future. *No* new code will make its way into the base distribution in future without sufficent documentation?
There really is *no* point in bunging in code that isn't complete and doesn't have documentation. All it becomes is an excercise in self-publicity and ego building, without really sharing anything of general use. If we keep putting forward software that only the 'experts' find useful then this community may as well become a 20 man outfit.
I realise there's some philosophical view points in this community that it should remain a primarily 'developer oriented' community, but its just plain wrong, and breaks down when you try and comunicate/share material with your peers and colleagues (the whol point of open source inthe first place).
Its impossible to collaborate if we tie peoples hands in this way....
I realise ther is no obligation for people who submit to provide all this, after all we should be grateful they are sharing anyway, but Open Source is a two way thing, and submitters benefit as well as donate... and think how much more we can *all* benefit for that sake of producing so supporting communication.
