[gambit-list] The future of Gambit

Christian Jaeger christian at pflanze.mine.nu
Sun Jan 18 09:34:21 EST 2009


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.




More information about the Gambit-list mailing list