Why You Do Not Use Lisp -- a survey

I should clarify: there certainly is documentation for common lisp, some of it quite good; the situation is that in many ways common lisp's documentation is outclassed by even php's documentation.

Let's turn this around: take a good look at php.net; put aside your disdain for the language (blech!) and just look at how the documentation is structured, in terms of organization (high level and low-level, like in what size chunks it's presented in).

Do you really think there is nothing to be learned from how the php people have assembled their official documentation?

I'd additionally argue that as nice as in-environment documentation is it's a sub-optimal approach to accessibility.

Part of the issue is for the abject beginner it multiplies the things to learn: everyone knows how to work firefox and google and can google something to see what turns up; having to learn how to work the in-environment documentation takes you from one problem ("how do i shot web?") to two problems ("how do i shot web?" and "how is docs found?"). A serious student will pick it up pretty quickly but .

The larger issue is that the lack of a central documentation + discussion hub means that there's no system taking the informal knowledge possessed by discrete practitioners -- stuff like what implementations of what functions on which platforms have unanticipated quirks, or what function non-newbies typically use instead of the function you're currently reading the docs for -- and capturing it for posterity in an easily-searchable format.

Some of that information can be gleaned from usenet and mailing list archives if you know to search there and have time to wade through flames and trolls and other gunk, but the rest of it is stuck in the minds of individuals and is therefore largely inaccessible.

The php approach (which is used by other projects, like eg mysql and pgsql) of having a central online documentation area with integrated user comments is that it provides a natural place for such informal knowledge to wind up; once it's there once it's there for everyone (and can be googled and so on).

You could create an in-environment system that had most of these advantages -- some "social" version of the docs, essentially a wiki-ish system -- but that's hypothetical, and I'm talking concretely, and concretely the available common lisp documentation is largely outclassed by the documentation available for php (and for python, and java, and c#, and many others).

As a parting note you really shouldn't underestimate the advantage of dumping more information into a single page.

Much of the useful knowledge about a language and its core libraries is knowing the logical structure of how everything fits together; much of this is never documented in any formal way, but can be inferred from an overview of the larger-scale organization.

When you present stuff all on one page it's pretty easy to take this in: notice how quickly you could tell the php strings api was poorly designed? That's b/c you could at a glance see everything that was relevant and infer the entire structure (or lack thereof).

When you present things in tiny little atomized chunks it requires much more effort for the reader to get the birds-eye view of the system, as the reader is not provided the convenience of seeing it all laid out in one place.