[racket-dev] Racket documentation

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/