[racket-dev] Racket documentation

On Sep 21, Matthias Felleisen wrote:
> On Sep 21, 2010, at 4:58 PM, Eli Barzilay wrote:
> 
> > And a side-comment -- having an on-line documentation is probably
> > going to make lots of people who follow the repository happy,
> > since compiling it is where the biggest chunk of time is spent.
> 
> No, no. See my comment. The improvements to the docs have to flow
> back to the repository version in some way.

No, no -- see *my* comment...  The improvements *should* flow back to
the repository -- of course -- that's the whole goal.  The thing that
I'm talking about in the above is that the default mode for setup is
to *not* build the docs, but the sources are still there -- they're
still being built *if* you explicitly request it, and the nightly
build must do that, since it's generating the on-line version that
everyone sees.


> I often program in an 'off line' manner, and I'd find on-line docs
> to be way too slow. I don't mind building the docs once a day.

To make it easier to read, I'll make the punchline before I proceed to
specify the details of why you won't have any problem.  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).
The best that you'd get is yet another scheme cookbook which will be
left to accumulate binary dust, with very few people who read it, and
very few of them who contribute to it.  My guess is that the
percentages were 2% who read the cookbook -- and 2% of the readers
contributed to it (and if I remember the rough numbers correctly, the
numbers of people who contributed was indeed on the order of 0.01% of
the number of users).

The main point is that if you want real community effort, then you
need *almost everyone* to be aware of it -- both to get more people to
read it, and to get more people to contribute to it.  This kind of
interraction just cannot happen in batch mode, with changes getting
through only on new releases, and worse, with participation only from
a few enthusiastics who put in the extra effort to use this community
site.  By making it the default you change the first 2% to 90% -- and
the activity around these improvements is now done by 100-200 people
instead of 4-5.

Back to your problem.  Here's how you and others can deal with "I want
to read the docs off-line":

* A normal user (who wants the released version and nothing else)
  downloads the docs, and from then on get to see only that.  The only
  difference is explicitly asking for the docs to be installed
  locally.

* A from-git user uses the the command-line flag to turn on building
  the docs -- and then you get to use them locally just like the
  above.

* Both users can download the new docs (with some menu entry or
  something like that) from time to time -- the stable-release user
  get updated docs without installing a new version, and the git user
  get updated docs cheaply, with just a download instead of running
  your own build.

  This is of course optional.  If the first user doesn't do it,
  they're left with static unchanged docs -- just like now.  If the
  second user doesn't do it, they need to continue paying cpu cycles
  for building the docs -- just like now.

* Another option that would be available is "use the on-line docs if
  they're accessible".  Then you'd get the local copy if you're not
  on-line.

As for speed -- that will not be an issue.  By far, the biggest
problem now is loading the JS index.  If the docs are on-line, then
the search can happen on the server side.  This is another big
benefit: the server side will be some racket code, therefore can do a
proper search, including full-text, complicated queries and whatever
you want.  You'll only pay for the network bandwidth.

Even better: *don't* do any searches -- no racket code, no apache
proxying, no worrying about server load.  Instead -- use the google
thing which was raised a short while ago.  We get the benefit of a
company that makes a living out of doing good search.

[Obviously, the docs won't even need to live in the repo like the rest
of the sources.  For a release-user-with-local-docs there's no
difference since they only care about downloading a local copy, how it
was built is irrelevant.  For a git-user-with-local-docs, this can be
done in a similar way to svn externals -- with the docs repo being
hooked in the normal repo (in collects/scribblings, for example), so
you can still edit them with git.]

Eventually, I'd like to see the local docs option used less and less,
so the focus can be on improving the on-line version.

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