Speaking of doing things differently...

There are two uses for documentation that I care about - sounds like a self-describing would handle the first one, when I'm staring at some code and wondering "WTF".

the second case I care about is when I have some idea that IMHO rocks the planet, and I'm sitting in front of an empty text editor wondering "HTH" (how the hell...). In this case, I want a big library of howtos, tagged up so I can wander the content and run into something that inspires the direction to take.

Case in point with scriptaculous - first time I tried to do something like fade out, refresh a div, then fade it back in, my code was hopelessly broken until I figured out I needed an event queue. Having an event queue that was self-documenting would be cool, but I still need the doco that gets me there.

1) From my experience nothing is more descriptive than a good old real life example (accompanied by a plain english). 2) Having standard documentation (jsDoc or natural docs) is a huge help and should not be underestimated. 3) Following certain code conventions is another way to make things speak for itself - once user gets familiar with certain aspects of a software, getting to know the rest of the system is easy and intuitive.

1. I would love to see a documentation similar to the one from prototypejs framework. I think it is quite good. But I would recommend a search function. for every method / class / module there should be some example code.
2. As mentioned before, guides and how-tos would be great. Reading some good code can be so helpful.
3. And then there is the "other" stuff. I.e. I really like your effects cheatsheet. It would be great if we would see more of this.

That's not that revolutionary... maybe for programming languages, but not for unix commands ;-)

Now if you can just get the code to WRITE itself, then all would be great ;-)

Well my solution would require that the user is developing using Firebug but...

I don't see why you couldn't have the ri-type functionality with Firebug, where the documentation is stored somewhere on the tubes and some Ajax function retrieves it and displays the docs in Firebug console:

// This is the specific package that developers write var Dialogs = { documentation = "http://documentation.com/Dialogs"

alertBox: function(warningMsg) {
    window.alert(warningMsg);
}
question: function(question) {
    return window.prompt(question);
}

}

// This would be the help framework package var Help = { /** * Retrieves the documentation for this function on the interweb. */ lookup: function(functionName) { // 1. Convert fully qualified function name into url using the package's // documentation root URL plus the function name // // 2. Grab docs using AJAX // 3. Return String which populates in Firebug console } }

Help.lookup("Dialogs.alertBox")

AH! That came out awful with the formatting... I hope you get the idea.

One other idea...being JavaScript, I don't see why you couldn't assign all the packages and functions a helper method that kind of inverted the call. So in the example given previously, instead of saying:

Help.lookup("Dialogs.question")

you should be able to write:

// Given some global function ji ji(Dialogs.question)

or

// Dynamically assign help function to every function in your package at runtime Dialogs.question.help()

Smalltalk gives you self-documenting code to some extent, in that you can inspect code as you're writing or reading it. This is achieved with doc strings and reflection. An editor for JavaScript written in JavaScript could in theory do something similar but it could also in practice totally destroy your machine.

The big trend in documentation I like is YouTube. You can find documentation for nearly anything on YouTube, and it's always practical in the extreme. There's videos on vi, emacs, TextMate, Rails, automatic music generation in Haskell, all kinds of cool ish.

The other big thing I like in documentation is the idea that unit tests are documentation.