Exploration Through Example

Example-driven development, Agile testing, context-driven testing, Agile programming, Ruby, and other things of interest to Brian Marick

191.8

⇒

167.2

⇒

186.2

183.6

184.0

183.2

184.6

Thu, 08 Sep 2005

Chad Fowler's book

The Pragmatic Press has published Chad Fowler's book My Job Went to India (And All I Got Was This Lousy Book). I haven't read it, but I know Chad and he did write an article for me. The article was about ways to think about career choices, tricks for keeping your skills up to date, and advice on marketing yourself for the marketing-averse. The book appears to be on the same topics. Check it out.

## Posted at 11:49 in category /misc [permalink] [top]

Unit tests used to generate documentation

Grig Gheorghiu has been poking around with the idea of using tests to generate documentation. Here is what he's been doing. Here is a sample of API documentation that another project generates from this code. (Note: the tests aren't written in xUnit style with explicit asserts, but rather by using a line markup style that I first saw in Updoc.)

(Grig's summary note here.)

See also Brian Button's PDF article about tests as documentation (from Better Software). Brian's article isn't about generating documentation, it's (mainly) about how to write tests so that they're useful explanations of how to use an API.

Fit uses the "look at the tests themselves" style, since the tests are HTML. I find myself fiddling around, trying to make tests nicely readable, but I find I'm hobbled by the lack of a good HTML editor (much less a good Fit-aware HTML editor). I've been put off using Word because (a) my versions generate horrible-looking web pages, (b) I am morally offended by the garbage it generates as HTML source, (c) I try to avoid using binary files with version control systems because you can't usefully diff them, (d) it sometimes produces incorrect HTML (most memorably when it added extra columns to tables), and (e) I don't know how to script Word so that running the test I'm working on is one button click in IDEA. I haven't tried Open Office (because I think it's lagging on the Mac), though I've heard people prefer it to Word for HTML generation.

I like simple layouts, so simple HTML would be fine for me (were it easier to edit). If a colocated team wanted prettier documentation, I'd be suspicious of their focus and priorities. But if the onsite product owner has to bring the Marketing Department into the decision loop, and the Marketing Department is three floors up with important representatives in another city, and they're used to attractive Word documents, weaning them off of requirements documents in favor of annotated customer-facing tests will sometimes require a certain amount of flash. For example, it should be easy to drop in a wire-frame sketch of a GUI.

## Posted at 07:56 in category /agile [permalink] [top]