On Sep 21, Eli Barzilay wrote: > [... lots of stuff that he'll be happy if even two people read ...] > [as usual.]
The only concrete suggestion that I see here is the following. How practical it is is debatable. I'll try to make this short enough to be more effective than the previous post. * Drop the documentation from the default setup. Make it an optional step instead. Don't even include the .scrbl files in the released installers. * Make all the documentation tools (DrRacket, `help', etc) use the local documentation pages *if* they exist. Otherwise use the on-line version straight from the server. * Package the documentation as an optional file, which people can install if they want to. I know that there's a lot of schools that will want that -- so perhaps there should be some organized way to do this. Maybe some `raco get-me-a-local-copy-of-the-docs' command, or maybe some (simple!) gui dialog that can be used to do this -- simple enough to be implemented now, and later grow to the "choose additional packages to install" thing that is planned anyway. * On the other side of these schools, I think that most day-to-day Racket hackers would not see any difference, since many are probably using the on-line version anyway. (I know I do, if only to see the official version that everyone sees...) So for these people the result is going to be positive -- no need to install a ton of files, no need to translate `file:///some/dir/on/my/machine' to `http://docs.racket-lang.org/', no need to build the documentation. Together with this, there should be more awareness of the documentation being something more dynamic, and therefore start talking about older versions when such changes are relevant. That's probably the iffy part that makes it a harder pill to swallow. Like I said -- IMO the benefits are obvious and desirable. One thing is that fixing the docs is going to have an immediate effect -- you complain about a typo, I fix it, and the next day it's fixed for "everyone" (except for those that choose to install a local copy, of course). The questionable part is in the fact that Racket can move fast in some areas -- fast enough that writing version-independent documentation is pretty difficult. This needs some better solution -- maybe some back-door place where older versions are kept which is relevant for things that are more than N releases old. For example, I redesign some library and write it from scratch -- I shove the old documentation there, and the updated version will say "if you're using Racket v.N and below, go [here]". But this should be the exception, since most documentation work is improving things in general, and most "things" don't move that fast. Once that's in place, the download-the-documentation thing could use the updated version -- so I can update my documentation even if I keep the same racket version. Maybe there should be some way to give me all of the documentation pages that are relevant for my version, so I'll stop getting updates to some revised library if I don't have it. Also, when it's in place, it would become practical to talk about some on-line annotation thing, as I sketched in the previous post. Practical to make it doable as some kind of a server thing or whatever. -- ((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
