Speaking of doing things differently…

Thomas Fuchs, of Script.aculo.us fame, has gone out on his own again as a consultant. If you need some of the world’s best JavaScript expertise, he’s your man. Heck, I’d hire him. Or at least, I’d contribute design ideas and photographs for his site (which I did). A site which, by the way, is powered by the new engine for Scriptaculous 2.0—still in the works.

Speaking of Scripty 2… Thomas and I are working on an innovative help system for the new version. API docs are almost universally frustrating, so we’re thinking outside the box. Our goal? You should be able to ask any bit of library code to explain itself.

Take a moment to imagine that. And if you have any ideas, let me know!

The details aren’t hammered out yet but you can be sure I’ll write about them here as things progress. I’m thrilled to have a more active role in improving the usability of software—a deeper involvement than just creating cheat sheets or even working on visual interfaces. Text and code interfaces are just as interesting as the shinier, graphical kind. And helping a person get to “Aha!” is one of the most rewarding things you can do, I think.

No Comments

  1. David Bock says:

    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.

  2. kangax says:

    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.

  3. max says:
    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.
  4. random8r says:

    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 ;-)

  5. Matt Hughes says:

    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")

  6. Matt Hughes says:

    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()

  7. 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.

Leave a Reply

Hey, why not get a shiny
Freckle Time Tracking
account?