[racket-dev] Racket documentation

And also, the wiki software kinda blew in many ways.

One of the biggest ways was a small thing with, I think, big 
implications: the software would by default add an attribution line for 
each edit, encouraging people to view the page as a dumbed-down Web 
commenting forum to append a comment to, rather than as a coherent 
document to refine holistically.

Also, depersonalization can be good: when there are no authorship names 
at all on a page, some people will have less resistance to making 
improvements.  This also removes some of the incentive to contribute for 
some people, which can cost the document some good contributions but 
also scare off some low-quality contributions (see, as cautionary tale: 
Java sites).  I think that removing incentive alone is not a net loss, 
and that depersonalization overall is a big net win.

Neil Van Dyke wrote at 09/22/2010 03:53 AM:
> Eli Barzilay wrote at 09/22/2010 01:18 AM:
>> The punchline is that your desire to use a local copy is in direct 
>> contradiction with the desire to get community involvement in 
>> improving the docs. No matter what facility is available for the 
>> community to discuss and supplement the docs -- if you have to go out 
>> of your way to see it, then you (the collective) just won't do it 
>> (statistically speaking).
>>   
>
> I think that you can make online docs sufficiently immediate 
> value-added that people are drawn to use those.
>
> This can be done without compromising local-copy docs.  If you did the 
> online right, everyone knows that they get immediate benefit from the 
> value-add of the online docs, so they must have a good reason when 
> they use local copy.
>
> For a simple example of docs similar to Racket's can be online and 
> participatory to some degree, see PostgreSQL's.  They have their 
> well-structured and well-edited manuals, and online you can browse a 
> version with old-school community annotations at the bottom of each 
> page.  I've found some of the annotations very helpful, and I'd hope 
> that they feed future versions of the well-edited manuals.
>
> You could also go more of a Wikipedia route.  But you don't have a 
> million contributors, and you will be spending lots of effort on 
> quality control, and with a relatively small contributor pool you have 
> to be more cautious about alienating people when a contribution really 
> needs to be excised.
>
> Whatever you do, I hope that the goodness of well-edited local-copy 
> docs is not compromised.
>
> Also keep in mind that some of us think that, when working on library 
> code or documentation, the interface should present both code and doc 
> easily.  Usually, with dumb tools, that means JavaDoc-like embedded 
> documentation.  I have a goal to make Racket support this better in 
> the future, and I hope that any new online docs thing won't get in the 
> way, and that I can be compatible with that.
>
>> The best that you'd get is yet another scheme cookbook 
>
> I think that some of the problems that the Scheme Cookbook encountered 
> are relevant to Racket.
>
> One is that a few characters of Perl operators from some Perl Cookbook 
> item, in the Scheme Cookbook could become a huge page full of 
> different verbose, cryptic, and so-so quality attempts to do a 
> comparable thing in Scheme.  (Which, in hindsight, should not have 
> been surprising, when Schemers are involved.)  I finally decided that 
> most of the cookbook entries would ideally mostly be pointers to 
> reusable code libraries (*not* copy&paste&munge), which led to me to 
> silly extremes like: http://www.neilvandyke.org/tabexpand-scheme/
>
> There were also various quality control problems for various reasons.  
> I got disenchanted after realizing that messes were being created 
> faster than good content, and that it would've been much easier for me 
> to do something correctly from scratch than find a politic way to fix 
> an existing entry or wrestle with the wiki software to reverse some 
> bizarre structure change some user had done.  (This is actually much 
> like software development in general.)
>
> A problem that the Racket online docs *won't* necessarily have is that 
> of scope: as I recall, the Scheme Cookbook was originally mostly 
> PLT-specific, and some dork (me) advocated strongly that the Cookbook 
> cover other Scheme implementations (e.g., R5RS whenever possible, then 
> separate out the various implementation-specifics within an entry).  
> This turned out to be additional mess and bulk.  Racket will still 
> have to decide what to do about version differences, but any mess will 
> be a lot smaller and simpler to organize.
>
-- 
http://www.neilvandyke.org/