Comment by frig | Hacker News Reader

Comment by frig | Hacker News Reader

Parent Full thread

Do you notice you just re-linked the hyperspec on Franz instead of Lispwork's site?

I thought you'd link to this, which is better:

http://www.franz.com/support/documentation/8.1/doc/contents....

...which I'd say is probably the best of the online manuals.

But more to the point:

There are minor issues with the formatting of the hyperspec no one's bothered fixing. Aside from the lack of a pretty stylesheet and the lack of wiki-style user comments

The most obvious is that if I eg go to the Strings or Array section it just gives me a page with a sub-table of contents; it'd be a lot friendlier to have all the Array or String docs on a single html page.

This wouldn't even be that hard to implement, and the "moar docs on one page" approach to online docs keeps winning out for a reason (it's easier to find what you're looking for if you only know approximately where it is if you can get everything that might be related on a single page and ctrl-f your way through it; having deeply-nested content is far unfriendlier).

I do think the hyperspec is not very well-thought-through as end-user documentation.

It mixes levels of concerns that ought to be separate; someone reading documentation with the goal of finding out if there's a built-in function for "split a string delimited by a particular character into a list of strings?" has very different requirements from someone who needs to know how strings are implemented, for example.

IMHO the hyperspec tries to do both; it's fine as a nitty-gritty reference but could be improved as a day-to-day programmer's reference.

Python's docs are a good example of end-user documentation done right. They have a clearly-delineated split between the language specification ( http://docs.python.org/reference/index.html ) and the standard library specification ( http://docs.python.org/library/index.html ) and additional, separate documentation over lower-level aspects of implementation.

Each body of documentation is organized for the convenience of its typical user.

The hyperspec was written before programming was watered down for the hurried masses.

There are at least two dead-tree manuals other than the hyperspec; CLtL2 and the book by Franz.

Nearly all your documentation reading will be done within your development environment anyway.

Yes all of this I know; you claimed common lisp has superior documentation to php and I've consistently shown you ways in which even php's documentation is superior to that possessed by common lisp at this time (at least in any sense that matters to me).

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.

Reply on news.ycombinator.com