[racket-dev] Racket documentation

[Sorry, I planned on some short and concrete description, but ended
writing a blog-post-like piece of text...  FWIW, I would love it if
someone takes this on seriously.]


On Sep 21, Everett Morse wrote:
> I had some thoughts about Racket's documentation compared to PHP's
> last night, so this morning I wrote up a blog post about it.
> [...]

You have some good points there, IMO.  There are several problems with
the current state of the Racket documentation, on top of a whole bunch
of very good things with it.

The good thing with it is the separation between "guides" and
"references".  When you look at a piece of functionality, there's
always a tension between explaining it to newbies (and in this context
"newbies" is anyone who doesn't know about a particular functionality,
so it includes everyone -- not just people who are new to the language
as a whole), and writing a detailed and accurate reference.  Having
both guides and references mean that a documentation writer is free of
this tension -- and write exclusively in one of the two modes.

But the bad thing is that there's not enough connectivity between the
two documents (I'm thinking of the reference and the "Guide" manuals),
and somehow the links between them are not obvious enough.  (This is
judging by reactions, since I rarely read the guides when I'm looking
for information.)  Improving that should be a welcome goal.

Another problem is that there's not enough guides -- for most random
libraries there's just a reference and no investment in a proper
guide.  In some cases a guide that provides a high-level view of a
library is sorely missing -- jumping right into the reference can
often miss important questions like "what needs does this library
fill?".  There are also cases where a guide is not really needed,
since the library is more narrow and there's no need for a high
level/intorduction kind of view.

But most frequently, and this is a meta-level problem, there's a need
to write a single piece of documentation -- then water it and let it
grow for a while: add more high level description at the top of the
library's page, then grow that to a full section, then add some
subsections, and then decide to split the whole thing into a guide and
a reference.  This whole transition is very hard to do -- mostly
because the initial documentation is written by the library's author
-- and the author is constantly in a race to improve things, add
features, redesign things, etc -- and the documentation is often a
second class citizen in this whole activity.

In some cases the documentation doesn't change at all.  New functions
are added, of course, but then they're documented "reference style",
and the high-level parts are rarely changing.  Worse: such changes
often wait for the author -- who is not only busy with working on the
code (and in the Racket case, it's often "codes") -- but in addition,
the author doesn't have a good high-level perspective on a certain
library.  They *know* what it is for -- since it was *their* itch that
started the whole thing -- but it's very difficult to put yourself in
the shoes of some random hacker who is new to the library.

So, IMO, a good solution is exactly what Matthias suggested.  It's
really best if there is some place to have everyone contribute to
improving the docs.  This doesn't even mean editing the sources
directly: just a place for user-comments would be enough.  A place
where you can ask questions, answer questions, suggest revisions, give
general hints, or write your own mini-tutorial -- even if it's only
one function that you're writing this tutorial for.  (There's no
shortage of single functions or small function clusters that could
have their own tutorials -- there's probably enough people on this
list that have taught in classes and know that something like `fold'
could really use a tutorial, not to mention things like
`current-custodian'...)

As for the technical details, there are some problems to overcome.
The first thing is presentation.  It could work best if there was some
way to have some split view (maybe something like the google side-bar
thing) where people can do this kind of interaction.  It should be
some wiki-like editable thing, where a library documentation writer
can participate in the discussion -- for example, see a question and
answer it by improving the docs for that question.

But this is the easy part...

I see two hard parts on top of this, both are related to making this
kind of communication work.

* On one side, there is the interaction between the people who use the
  side-bar thing (whatever form it has) and the documentation
  writer/s.  It would be nice if there was a way to put alerts on
  these things -- so, for example, I document `foo' and whenever
  someone uses the system I get an email telling me that there was a
  comment there.  It would also be nice to be able to have these
  alerts for the people who write the comments -- if I ask a question,
  I'd like the system to tell me when there's an answer, rather than
  keep a browser window open and refresh it whenever I happen to
  remember that it's there.  When this communication gets more
  serious, it probably needs to go off onto email or something
  equivalent -- for example, if I see some suggestions, I'd like to
  try some revision, then send the whole revised text to the person
  who suggested it; or if I have some concrete suggestions on some
  text I'd want to send it to the author directly instead of having a
  side-bar comment with "Here is what I think that whole section
  should say: [3 pages of intro text]".

* On the other side, there is the problem of making people use this
  system.  Currently, there is no easy way to do that: you open the
  documentation and it's some static text on a local file.  A first
  good step would be some link that would (maybe) jump to the on-line
  version of the text, with the comments and everything.  (That
  on-line version would need to be the one from the nightly builds, of
  course.)

  But that's not enough, unless the links are made very obvious
  somehow.  Ideally, I'd want that contents to always be visible --
  but I don't know how to do that in a practical way that doesn't
  break things.  One major problem is that the documentation setup is
  one that works from your own installation -- and for various reasons
  it looks impractical to move to an exclusively on-line documentation
  system.  So however this is implemented, it should be done in a way
  that doesn't get in the way of people who use the static pages.

  A followup problem is the documentation itself.  Right now we make a
  pretty big deal out of making the specific version of the
  documentation work for the specific version of racket you have
  installed.  Moving to a centralized on-line thing requires the
  documentation to be independent of your racket version -- or at
  least be "less dependant" on it.  (For example, there is no
  documentation of changes that happened at version X -- because our
  setup means that you always get the documentation for the version
  you have right now.)

  (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.)

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