[racket-dev] Racket documentation

On Sep 22, Neil Van Dyke wrote:
> 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.

I don't believe that this will ever be effective enough.  We have a
large number of newcomers (because it's being used in courses there's
a constant stream of new students who later move on), and these people
will never see it.  Also, IMO if you need to choose to use some
alternative, then many people will never bother doing so, and many
people will not do it because they'll want to stick with a blessed
version.


> 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.

Specifically, you don't have to have any reason if it's the default.


> Whatever you do, I hope that the goodness of well-edited local-copy
> docs is not compromised.

I'm imagining having the docs with an easy way to see the user
contributions/discussions/suggestions -- and the improvements to the
actual docs would be done continuously based on this feedback.


> 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.

Yeah -- that would be an issue of the doc sources are in a separate
place.  Doc sources that are in code (like a javadoc-like thing or a
literate programming thing) will have to stay there.

But given the overall excitement around this, I doubt that anything
will happen.


> I think that some of the problems that the Scheme Cookbook encountered 
> are relevant to Racket.  [...lots of issues with that wiki...]

These are all true, but they'd been much better still if there were
more people involved.  If you think about everybody that uses racket
having a (prominent) one-click access to the content, you get orders
of magnitude more eyes, and this can lead much better to a
self-organizing wikipedia-like effect.

-- 
          ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
                    http://barzilay.org/                   Maze is Life!