During the Torque development (a small javascript library to create animations on maps) we decided to use a markdown template to write there the reference API documentation:

https://gist.github.com/javisantana/6413167

some goodies about it:

- plain text

- easy to read without format

- plenty of tools to transform to html (or whatever)

- easy to parse if the project grows and it need to be transformed to something better

- nice starting point. Useful when you don’t know how/where to start

While I was coding I always had a vim window open with the documentation so I can update it at the same time I was changing the interface in the code. It’s the only way I’ve found to keep the API documentation up to date.

At the end this is another example of “stone soup" story. In this case putting this file in a doc folder and opening it every time you start to code remind you need to update it.