Monday, September 23, 2013

Living Documentation with Javascript

Documentation is an essential part of software development. Good documentation allows developers to collaborate and build upon each other's work, speeds up the onboarding process for new team members, and makes debugging easier.

However, many developers fail at writing documentation. Very often you'll find projects where:
  • There's no documentation, because developers never got around to it.
  • There's documentation, but it's so outdated it's practically useless.

This might not be a problem at first, but as a project grows in size (both in amount of code and in amount of developers), the lack of documentation starts taking a significant toll on development speed.

How to write documentation

The only way to make sure you'll get documentation written is by writing it before your code. If you wait until the code is ready or wait until you have spare time, chances are you'll never write your documentation.

Keeping documentation up-to-date is a bit trickier, but can be achieved through Living Documentation. The concept is pretty simple: If you can get your documentation to double up as tests, then you'll have documentation that never goes out of date (because your tests will fail if that ever happens).


There are several testing libraries for Javascript, and some of them can be used to produce Living  Documentation. However, after trying a few of them and struggling to get them to work like I wanted, I decided to write LiveSpecs.

LiveSpecs is based on 3 ideas:
  • Every project needs good documentation and test coverage
  • Documentation should never go out of date
  • Code samples are the best type of documentation
With LiveSpecs you can write code samples that are be displayed on your documentation site, but also run as part of your test suite.

JSCalc - An example application

JSCalc is an example application I wrote to demonstrate how LiveSpecs works. You can find the source code for JSCalc on the LiveSpecs example directory.

You can also visit to see the example running on your browser.

1) Read the documentation
When you open the site, you'll see something like this:

The cool thing about this documentation is that it includes examples where you can see how JSCalc should be used.

2) Try out the code
Even cooler than getting code examples is being able to try them out. If you click the "Try it out!" buttons, you'll see the code running in your browser. You can even tweak the code, modify some parameters and see what happens.

3) Run the examples as part of your test suite
If you open /docs/spec_runner.html you'll see a spec runner going through all your examples and verifying no errors are thrown. This is how it looks like when it finds an error:

You can also run the specs using PhantomJS, as explained here.

There's still a lot of work to be done to get LiveSpecs to version 1.0, but I hope you can try it out and let me know what you think.

No comments: