What JCite really is about is what I am going to call DDT: documentation-driven testing. It is a discipline that complements and, during the conception of an API, really comes before TDD: test-driven development.
There are quite a few articles extolling the virtues of test-driven development these days (here's one). And for good reason, too. Having done TDD for quite a while, I recently started combining it with documentation-driven design. This is what my open-source tool, JCite, is all about.
With this approach, I sketch out the most important use cases,combine them into the index of a tutorial (links plus teasers summarizing the use-case),flesh out the tutorial topics (and thus use-cases) one by one,develop the use-case tests in parallel to each topic,cite the important parts of the tests as actual code samples into the topic, andonly then start doing the implementation (this last step is accompanied by more tests, which are now more like unit-tests).In all, this is like literate programming, but of the use-case tests rather than the implementation code.
TDD already helps to make you focus on the user during API design. DDD takes the effect further by making you tell consistent and convinc…