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/
_________________________________________________
For list-related administrative tasks:
http://lists.racket-lang.org/listinfo/dev
