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