[racket-dev] Racket documentation

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!