NodeJS Documentation Deficit

I’ve recently started learning node.js as a development language and framework. I have to say it really rocks, despite some of the inconsistencies and gotchas of programming in JavaScript.

I haven’t done any serious JS programming since the early noughties - manually writing drag and drop DHTML libraries for IE5; long-lived HTTP requests in hidden iFrames in order to implement push/streaming to the browser. I certainly wouldn’t call those fond memories!

Anyway, the joy of global variable scope and inconsistent object creation idioms notwithstanding, the Javascript language is powerful and easy to read and understand, and comes with excellent support and tooling. (For anyone interested in learning – or improving – their javascript I can’t recommend Douglas Crockford’s videos/lectures strongly enough – see the link here)

Back to Node itself though. Fundamentally Node forces you to write in an asynchronous style (with a functional/closure syntax that makes this easy), which makes it very straightforward to write highly scalable applications. In principle Node runs an event-loop, and function calls are usually accompanied with a callback. The function executes asyncronously, and calls the callback when the job is done.

For example:

function doSomething(parameter1, parameter2, callback){
    //do something with the parameters
    var result = parameter1 + parameter2;
    var err = null;
    callback(err, result);
}

 doSomething("hello", "world", function(e,v){
    if(e){
        console.log("There was an error");
    }
    else{
        console.log(v);
    }
}

Given the framework is single threaded, It’s important to make sure that functions do not block, or take a long time to complete, but the consequence of adopting this approach is that you are forced to think carefully about concepts of performance from the ground up as part of designing an application, and that in turn makes for the finished article to be fast and highly scalable.

There are also some fantastic frameworks (e.g express) for pulling together web apps very quickly indeed, with support for templates, advanced routing, etc. In fact the ecosystem around Node is enormous and growing quickly (see http://modulecounts.com/ to see just how quickly). Modules are trivially easy to download and install, using a single tool packaged with Node called npm.

One major issue I’ve noticed however is that there is a major “documentation deficit” for many Node modules. Node modules typically have a readme.md file (markdown format) which is displayed on Github (the default source repository for node module development), and in most cases that is the extent of the documentation. Rarely is the full API of a module explicitly documented, and where it is the explanation of parameters, valid and invalid values, error codes, etc. is poor or non-existent. Some modules don’t bother with explicit documentation at all, and rely instead upon examples only. All to often even the example usage isn’t as documented examples, but is simply left as example source files included in a folder in the package. Of course example usage is valuable – but it is not an adequate substitute for a canonical API documentation.

Coming from the Java community, I’m really shocked by the absence of Node module documentation, and it’s not just that there isn’t widespread use of an API documentation tool like Javadoc for the Node world to generate hyperlinked/interactive docs. The documentation, the explanation, of a module’s usage simply does not exist for far too many packages.

Is this because Node is still in that immature, entrepreneurial, discovery phase? Is the Node world evolving and growing so fast, that no-one has any time to document things properly? I really don’t know, but I do think that Node needs to “grow up” and the community needs to mature a bit and start supporting itself with more than just code snippets. The platform is a wonderful way to design and build web apps, but in the long term it will be held back if the community only contributes code, without conveying how to maximise the use of that code.