[racket-dev] Racket documentation

Don't talk it to death with long emails. Help people to get this started. -- Matthias



On Sep 22, 2010, at 4:30 PM, Eli Barzilay wrote:

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