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:

• It’s really hard to refer to other things in Markdown. If you want to link to a different class, where is it? The answer changes whether you’re in GitHub, with its auto-generated permalinks, or on a website with different pages or different permalinks.
• Combining DIY documentation, as we have done with Mapbox.js+Leaflet, is a big ol’ hack that just doesn’t work well.
• Markdown tables are the farthest thing from tables possible, but we usually want function parameters to be in tables. Yes, I hear your groaning - this might not mean the HTML table element, but it means some HTML structure more complex than an ordered list.
• Markdown isn’t data: I really like it for text, but it just ain’t the one for everything else. And YAML doesn’t cut it. It isn’t simple and isn’t right for this purpose - using “YAML frontmatter” would restrict the way we separate and format docs.

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.