I think you have a valid point (other than in the case of the Vagrant docs, which I absolutely detest [0]).

The simplest way to make good-looking docs might just be to 'just use Sphinx' (as does Flask, mentioned and http://docs.python.org/ and [many others][1].

Another example of amazing docs (they've always been pretty decent, but amazing in their most recent style) are the PHP docs: http://www.php.net/manual/en/function.pg-affected-rows.php

The docs are a necessity to make up for the shoddy, inconsistent patchwork that is their language design, but they are damned well designed and easy-to-use for the wading through flat scope that is required by those who use the language.

Similarly, styles based on YARD/codo (http://coffeedoc.info/github/coffeedoc/codo/master/) are pretty nice for API references.

[0]: Disappearing sidebar when you resize to narrow, huge amounts of spacing everywhere and sidebar names that can't be expanded without navigating to their root. :/

[1]: http://sphinx-doc.org/examples.html

Ooooh the PHP ones are even better than they used to be, I hadn't checked in a while. I have always loved the user comments in docs idea. I've noticed so many bugs, gotchas and idiomatic patterns simply by looking at those comments. I bet it gives the devs a good idea on what to work on next, too. It didn't used to have votes which was bad because it perpetuated bad advice sometimes, but now it seems they have that too!

When Racketeers talk about documentation, they're not talking about the sort of documentation that you are holding out as better. They're not talking CSS and markup and formatting. No.

When Racketeers talk about documentation, they are speaking in Lisp and the context is code as data and data as code. When Racketeers talk about documentation they are talking about Scribble.

http://docs.racket-lang.org/scribble/index.html

Scribble is Racket's documentation tool. It adds an independent documentation phase to the Lisp expansion. Here is Mathew Flatt introducing it:

http://vimeo.com/6630691

None of the examples even comes close. The closest thing is EMACS Org.mode, but it is still ad hoc to whatever language one is documenting.

My critique was more on the visual side of things. I think it matters. That said, onto your comment:

I liked the presentation. The @ notation is kinda neat and elegant, and no doubt enabled by the ridiculous power macros give you in terms of modifying how everything is parsed. It's cool that it's implemented as a DrScheme lang, and it can run and is all code-is-data-y, and it's not a totally separate language. However, I don't really see anything in here that any modern document processor (say http://sphinx-doc.org/) can't perform.

The second-last question brings up a great point that when you tightly couple your documentation language with the platform (PLT), you run the risk of it being a PITA to use it to document other languages. I think the presenter's solution of automatically creating stub classes and such is really unsatisfactory and kinda kills the benefits.

So there you have it, there are pluses and minuses. I think Scribble is neat, but it's really not all that out of the ordinary.. It's definitely not true that "nothing comes close".

What sets scribble apart are:

* That it's a full programming language, unlike systems like Markdown, or Sphinx, or JavaDoc, or other similar systems. But it also doesn't sacrifice being easy to write, the way that text is easy to write.

* That is works properly with binding. If you're documenting a function, you want to document the correct one -- that's handled with binding, the same way it works when programming. When you're writing an example, the same should be true -- again, handled with binding in Scribble. This works for _programs_, not just identifiers, which is what it looks like Sphinx does. That's why, for example, every single identifier in the examples on http://racket-lang.org is hyperlinked to its documentation. If you go to http://docs.python.org/3/tutorial/controlflow.html , the examples aren't hyperlinked at all.

I think the binding is really the big thing here. That basically the whole module environment is also available to scribble since it is also legitimate code, and it's being executed by the same interpreter, in essence.

I'm unconvinced that this is not possible otherwise though. If you're parsing the darn language to get to the AST to generate all the module names, contents, etc, I don't see why you couldn't have access to all that info when generating an example code block.

Example:

http://wtf.tw/etc/pygments/pygments/formatters/html.py.html

Although I don't know why it's not more common.

Right, people have certainly implemented hyperlinked versions of code by re-implementing the parser etc. LXR is an excellent example of this. What sets Scribble apart is that

* It's a documentation system, not just a code formatter.

* It's a programmable documentation system, and the code that _implements_ your documentation is kept appropriately separate from the code that you are documenting. This makes use of Racket's support for phases.

* That it doesn't re-implement the parser etc, but can use the built-in one, because of Racket's macros.

And, as you say, even if none of this was unique, there's the fact that Racket does it, and has 500k lines of documentation, all done comprehensively in this style.

Beware the Blub Paradox.

http://www.paulgraham.com/avg.html

I've read "beating the averages" about a billion times, along with all the other PG essays. I was (and still am) a fan. I took several classes using PLT scheme and I've used PLT scheme for a reasonable amount for other tasks (wasn't called racket then). I've also dabbled with some lisps. I've read the little schemer, I've went through the wizard book. I've written the obligatory metacircular evaluator. All this got me excited.

Over the years though, I've done my best to learn the lessons and move on.

Is it really a surprise that lisp, an aged tool of refined elegance, was a competitive advantage over the other popular languages in 1997, which were still in their neanderthal phase? I'm not sure if the difference is that huge these days though. While in the olden days languages seemingly refused to learn from the teachings of lisp, it seems today they steal from lisp like pop artists steal from each other. Say, a ruby DSL with blocks and other tricks is not as flexible as a defmacro based lisp one, but could there maybe be a tradeoff here?

Writing in lisps give me what I call the intellectual warm-fuzzies. I get to use many elegant tools to form abstractions upon abstractions to create the DSL for my problem domain. I like that. Some call it doing the Right Thing. The polar opposite of duct-tape programming if you will. A quote from the article: "to translate this program into C++ they literally had to write a Lisp interpreter [so basically a lisp-to-c++ compiler]". This is exactly the sort of thing I'm talking about. It's cute. It's the Right Thing. Rewriting the code by hand in C++ is for plebians.

And, given enough code, maybe writing the lisp-to-c++ compiler is less effort than a rewrite initially. Maybe. I'll allow the benefit of the doubt. But what about the machine-outputted C++? Is the code idiomatic? Is it performant? Who wants to maintain machine generated code? Who wants to maintain a custom compiler? Maybe none of these are problems, but my vote is that it's unlikely.

The blub paradox applies much more strongly (or maybe I could say "only applies") when you haven't been exposed. When you, in your arrogance, refuse to try something different. I've traveled up and down the proverbial ladder, and I know where I'm comfortable. For now. I suspect it'll change sooner or later.

What astounds me is the arrogance to claim that lisp(s) is the One True Language, and anyone who doesn't agree Just Doesn't Get It. It's like the audacity a religious person has in claiming that their god is the one and only, in effect taking for idiots all the millions of remaining people who ever existed and sincerely believed in their own creation stories. What are the chances that everyone is stupid and you're the only enlightened one?

In response, I give you the Bipolar Lisp Programmer: http://www.lambdassociates.org/blog/bipolar.htm

I disagree with your examples. Taste is an odd thing that way.

Specifically, previous/next are great if you are reading it straight through. I agree this isn't that likely, but is nice to have. (I have actually used these. Recently, even.)

The fonts and colors are mostly pleasant. I can see how you would like other schemes. But I can't find anything atrocious.

I love how linked everything is. Specifically in the code samples. Even in the intro[1], all code samples are linked to the docs for what is there. Contrast this with the flask documentation, where if I want to see what @app.route does, I have to go find it elsewhere.

So, yes. There are things I would find to complain about if asked to look for them. At no point in actually perusing and using the site have these ever bothered me. And there are more niceties thrown in there that have made things easier than any of the complaints you mentioned.

[1] http://docs.racket-lang.org/guide/intro.html

> http://junit.sourceforge.net/javadoc/ (ughhhh)

Despite me not really liking Java all that much, the javadocs can be very useful; although in that example they chose a bad non-default colour - black on (dark) green is difficult to read.

Here's a better example, they normally look more like this: http://www.jdom.org/docs/apidocs/

I think we just disagree on taste for documentation pages. For example, I find the Vagrant docs somewhat garish and hard to read.

The current look of the Racket documentation was designed by Matthew Butterick. You can see his excellent book on typography and design here: http://practicaltypography.com/ -- and it was made with Scribble, the same system that generates Racket's documentation.