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]

About Brian Marick
I consult mainly on Agile software development, with a special focus on how testing fits in.

Contact me here: marick@exampler.com.




Agile Testing Directions
Tests and examples
Technology-facing programmer support
Business-facing team support
Business-facing product critiques
Technology-facing product critiques
Testers on agile projects

Permalink to this list


Working your way out of the automated GUI testing tarpit
  1. Three ways of writing the same test
  2. A test should deduce its setup path
  3. Convert the suite one failure at a time
  4. You should be able to get to any page in one step
  5. Extract fast tests about single pages
  6. Link checking without clicking on links
  7. Workflow tests remain GUI tests
Permalink to this list


Design-Driven Test-Driven Design
Creating a test
Making it (barely) run
Views and presenters appear
Hooking up the real GUI


Popular Articles
A roadmap for testing on an agile project: When consulting on testing in Agile projects, I like to call this plan "what I'm biased toward."

Tacit knowledge: Experts often have no theory of their work. They simply perform skillfully.

Process and personality: Every article on methodology implicitly begins "Let's talk about me."


Related Weblogs

Wayne Allen
James Bach
Laurent Bossavit
William Caputo
Mike Clark
Rachel Davies
Esther Derby
Michael Feathers
Developer Testing
Chad Fowler
Martin Fowler
Alan Francis
Elisabeth Hendrickson
Grig Gheorghiu
Andy Hunt
Ben Hyde
Ron Jeffries
Jonathan Kohl
Dave Liebreich
Jeff Patton
Bret Pettichord
Hiring Johanna Rothman
Managing Johanna Rothman
Kevin Rutherford
Christian Sepulveda
James Shore
Jeff Sutherland
Pragmatic Dave Thomas
Glenn Vanderburg
Greg Vaughn
Eugene Wallingford
Jim Weirich


Where to Find Me

Software Practice Advancement


All of 2006
All of 2005
All of 2004
All of 2003



Agile Alliance Logo