Literal testing
a BOF I went to listen handled about how one should create user documentation for a framework or API. The speaker (Peter Arrenbrecht) had an interesting view on that: “For a certain use case, first write a tutorial and use a lot of examples, then from these examples build your API. This will result in an API with more understandable methods and classnames for your API.” To elaborate a bit. Because you write your tutorial with real examples your API comes forth of the tutorial which forces you to think about the way the API is build.
There are 2 approaches in this, code first and prose first.
in code first you write use case oriented tests which can be used as example in tutorial. With a tool like bumblebee you can transform your usecase oriented tests javadoc to a tutorial document.
In prose first you write the documentation and with e.g. JCite you mark parts in your tests through annotations and when running JCite it will pick up the parts and put them in your documentation.
JCite is actually good for that. because when you start refactoring stuff in your code (hence also in your tests) and parse it again with JCite it will warn you about things that changed, somehow forcing you to take a look at the documentation of the parts you refactored/changed and triggering your brain to see if the change made sense.