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