Andrew Lentvorski wrote:
Marc Feeley wrote:
Brad, as you know writing good documentation is not a simple matter... it takes time and considerable effort (at least for me) to write something that is correct and readable. My experience is that few people actually read documentation anymore, so the incentive is low.
This is true, but probably not for the reason most people think.
What I do read is *example code*. A chunk of code that uses feature X to do some useful task Y is better than just about any amount of API documentation ever produced.
Getting people to push more code to the dumping grounds is probably vastly more useful than the API docs.
I think suggesting that examples are more useful than docs is a bit disproportionate; I did read more docs than other people's code to get my work done during the last ten years anyway. (And I think I've spent more time reading the source of the respective system/library I was using than reading code from other users.)
That's not to say that the dumping ground couldn't be useful, but I think what it is missing currently is active feedback; to make this easier, I think it would help much if all code there would be offered in a VCS. Not only makes this contributing changes back to the author easier, but it also allows for the readers of the dumping ground to actually see the feedback that happened. Offering VCS access is easy enough (tar including .git, or better pointing to an online repo; check out repo.or.cz, also offering a git repo over http on any http server you've got write access to is easy). Does anyone think easy Git hosting on the Gambit site (or even somehow making dumping ground offerings being checked in automatically) would be worthwhile?
Christian.