HN Explorer

Ask HN: The Most Useful Format for API Documentation

2 points by sago ↗ HN
I'm working on the documentation for a new open source system for interactive fiction. It consists of a DSL and an API in Javascript and C#. I have some thoughts about what documentation I've liked, both practically and aesthetically. But it is clear there isn't yet a consensus and standard. There are a lot that model the Javadoc approach, some that use the Docco literate approach. And then lots of the tools I rely on (Node, jQuery, Mozilla's MDN, etc) use ad-hoc approaches.

So is there an approach that works well for you? Are there good approaches for multi-language systems? Why do you think there isn't a consensus?

1 comment

[ 3.0 ms ] story [ 12.3 ms ] thread
andrew-lucker
As a project ages more thought shifts from development to maintenance and external concerns. What is good for a young project is usually not a good fit for a mature project. Specifically, young projects tend to care more about automated documentation generated from code, whereas mature projects just want a good content management system.