How Everyone Documents
- 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
tableelement, 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.
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.
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.