Skip to main content

Documentation Driven Development - Other Takes On The Theme

I googled for "Documentation Driven Development" and came up with a number of links (why the heck did I not do this sooner?).
  • SpliceIt seem to be doing it, but don't cite tests. There is no mention of integration with use-case-level tests.
  • Vincent Massol had the experience when writing books about frameworks - always improved the underlying code. The message is: you have to be serious about writing good docs. Otherwise the effect is lost.
  • Korby Parnell just thinks about it, but some comments point to people with experience doing it.
  • IEEE has an article about DDD for real time systems. Also seems to take it as far as code-generation. I haven't read it.
  • Miguel dos Santos has little to add, but there is a nice comment by someone called "Tania" about applying the idea of documenting the "why" more generally.
In the groups, I got:
  • Ilja Preuss's take is a bit too limited for me. In my experience, good DDD docs focus on tasks, not classes and methods.
  • Michele Simionato is spot on. Already did it in 2003, in Python. Which, incidentally, executes the DDD/Citing idea very nicely indeed.
  • Phil Thomson, as a half-joke, prompts Dave Thomas to drive DDD of RubyGems with his book. Funnily, it seems that Andy Hunt and Dave Thomas have used a JCite-like approach for every one of their books. They have some home-grown macros to make compiling and checking the example code automatic.
The search for "Documentation Driven Testing" is less rewarding.

Comments

Popular posts from this blog

Threaded chat article and demo

While nothing major, managing threaded conversations in chat has bothered me for quite a while. Yesterday I had an idea on how to improve matters:
Works using existing chat infrastructure. Needs only augmented clients.Plays well even if other party uses a non-thread aware chat tool.Separates threads automatically based on interaction patterns.I've written an article and have created an online demo about it. Discussion welcome.

Beyond TDD: Documentation 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…

Access 2003 and the DCOM Server Process Launcher

Here's a hint: Don't disable the "DCOM Server Process Launcher" service on XP SP2. It may look like one heck of a vulnerability when you really don't use DCOM at all, but, unfortunately, Microsoft Access 2003 does. It will simply open an instant message box stating "A problem occurred while Microsoft Access was communicating with the OLE server or ActiveX Control." if the service is not running.