Tom MacWright

How Everyone Documents

Markdown Documents

This is what we’ve done with Mapbox.js and Leaflet does it in HTML. Heck, node takes this approach. But I’ve felt the burn of the “just do it manually” approach:

Documentation Generation

This is popular in other languages, like Go and Python: you write some ‘magic comments’ in your code and a tool analyses your code to extract them as data and turn them into readable formats. A neat bonus is that fancy coding environments can read these docs too and give inline help: the most famous example is Intellisense, which ranks just below Word For Mac 98 as Microsoft’s best work.

Literate Programming

The literate programming approach is of historical and linguistic interest: instead of documenting the outside interface of a program, you try to make all of the guts understandable, documenting individual loops and variables in crazy detail. I’ve tinkered with this, building literate-raytracer, simple-statistics, and literate-game-of-life in this style. It’s a fantastic exercise in questioning your confidence: is this really good code, and do I really understand what I’m writing at a deep level? But it’s the highest work level of any documentation style, and it fails dramatically at being skimmable: I’ve never seen literate programming as an effective API doc.

July 05, 2015 @tmcw