Readable Fit Documents

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
checkthat visibility frominvisible node 1.1is(nothing)
checkthat visibility fromnode 1.1.1is(nothing)
checkthat visibility fromnode 1isnode 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.1isinvisible
node 1.1.1isinvisible
node 1isvisible

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 ListNodeVisible?
  • node 1
    • invisible node 1.1
      • node 1.1.1
invisible node 1.1invisible
node 1.1.1invisible
node 1visible

Ick.

If you liked this entry, check out my best writing and presentations, and consider subscribing to updates by email or RSS.