Brian Marick has been doing some really great work in the area of making Fit documents readable. I've applied some of his ideas in creating the Fit specification--mostly simple things, like using alternate fonts to emphasize different things.

In his latest blog entry about the subject, he provides this example:

com.exampler.fixtures.dofixtures.Visibility

Visibility

Making a node invisible makes its descendants invisible, no matter where the search begins.

create

node 1 invisible node 1.1 node 1.1.1

check	that visibility from	invisible node 1.1	is	(nothing)
check	that visibility from	node 1.1.1	is	(nothing)
check	that visibility from	node 1	is	node 1

The engine that makes this work is Rick Mugridge's DoFixture, part of his Fit Library, which will be coming out when his and Ward Cunningham's Fit book comes out in June.

I love the readability of Brian's example. It inspired me to try some variants. Brian's approach is an example of an imperative document style. His example tells you what to do, step by step. I prefer a declarative style, which tells you facts rather than giving you a list of steps to follow. I tried rewriting Brian's example in that form:

com.exampler.fixtures.dofixtures.Visibility

Visibility

Invisible nodes' descendants are invisible too, no matter where the search begins.

given

node 1 invisible node 1.1 node 1.1.1

invisible node 1.1	is	invisible
node 1.1.1	is	invisible
node 1	is	visible

I like the way this approach turned out. It's declarative, short, and sweet. It also has fewer "non-data" words, as Brian puts it. There's no Fit fixtures yet that make it work, but they certainly could be written.

In the process of writing this entry, I tried replicating Brian's example with just a ColumnFixture. The result was definitely not as easy to read. I even cheated a bit and used "graceful names," a feature that isn't yet in core Fit. See for yourself:

Visibility

Invisible nodes' descendants are invisible too, no matter where the search begins.

fixture.Visibility
Node List	Node	Visible?
node 1 invisible node 1.1 node 1.1.1	invisible node 1.1	invisible
	node 1.1.1	invisible
	node 1	visible

Ick.