Test-driven API documentation
My latest interest is in innovative and useful ways of doing API documentation. In a comment on a stackoverflow post, Aaron Digulla suggests that we should use tests for the example code in our API documentation.
Here’s the relevant part of Aaron Digulla’s comment:
In my case, I use two tools:
1. A Wiki to give you the big picture… [snip]
2. Lots of tests which show how you can use the code. You need to write them anyway, so write them just like any other code (clean and readable) and turn them into your examples. Main advantages: Documentation can lie, be wrong or be outdated. Tests Always Tell The Truth (TATTT).
Now, that sounds interesting!
Has anyone else tried this, and do you have any examples that we can take a look at? It would be great to hear how well it works. For example, I wonder if the granularity of the tests matches the granularity required for documentation examples. How do you pick the tests that are relevant for the documentation?
All comments greatly appreciated. 🙂
Going off topic: It’s been a while since we’ve had a tree in one of my posts. Here you go: