Print

More on Readable Fit Documents

04 Mar, 2005

Brian Marick followed up on my earlier blog posting and noted that his document describes something different than mine does. In his example, the user "starts a search" at a particular node. Brian has examples (tests) showing how this works.

(By the way, Brian described my approach as "making Fit statements look more like they're for understanding than for testing." That's a perfect explanation. I see Fit as a tool for increasing understanding of requirements. The automated testing part is "just" a means to that end. You can read more about this in my Fit documentation trail.)

Here's one of Brian's examples, showing visibility from a certain node:

create
  • node 3
    • invisible node 3.1
    • node 3.2
      • node 3.2.1
checkthat visibility frominvisible node 3.1is(nothing)
checkthat visibility fromnode 3.2isnode 3.2, node 3.2.1
checkthat visibility fromnode 3isnode 3, node 3.2, node 3.2.1

What Brian's saying here is that if you start searching from "invisible node 3.1," you don't see anything. If you start searching from "node 3.2," you see node 3.2 and node 3.2.1. This is different than just saying that a node is visible or invisible, which is what I did.

This is a subtle point and I missed it the first time I read Brian's examples. The challenge is to make this point big and obvious. How to do that? The "is" notation I used before doesn't read clearly any more:

given
  • node 3
    • invisible node 3.1
    • node 3.2
      • node 3.2.1
invisible node 3.1is(nothing)
node 3.2isnode 3.2, node 3.2.1
node 3isnode 3, node 3.2, node 3.2.1

What if we use a different verb, like "has" or "sees?"

invisible node 3.1sees(nothing)
node 3.2seesnode 3.2, node 3.2.1
node 3seesnode 3, node 3.2, node 3.2.1

Still not very clear.

What if we did something completely different?

invisible node 3.1is(nothing)
node 3.2is
  • node 3.2
    • node 3.2.1
node 3is
  • node 3
    • node 3.2
      • node 3.2.1

That's certainly interesting.

Something that keeps coming to mind is that, if we're describing something and we keep repeating certain words, then perhaps we should turn those into column headers in order to eliminate duplication. In other words, if we're describing this conversationally and we say:

Given this node structure (points to node structure), searching from invisible node 3.1 finds nothing. Searching from node 3.2 finds node 3.2 and node 3.2.1, and searching from node 3 finds nodes 3, 3.2, and 3.2.1.

That can be transcribed as:

Given [...]

Searching from invisible node 3.1 finds (nothing)
Searching from node 3.2 finds node 3.2, node 3.2.1
Searching from node 3 finds node 3, 3.2, node 3.2.1

Actually, I think this is my favorite combination of verbs so far. It has the disadvantage of lots of duplication, though. We can also eliminate the duplicate "Searching from" and "finds" verbs by turning them into columns:

Given [...]

Searching from...Finds...
invisible node 3.1(nothing)
node 3.2node 3.2, node 3.2.1
node 3node 3, node 3.2, node 3.2.1

Wow. That turned out much better than I expected. Let's tie all the different ideas together:

Given
  • node 3
    • invisible node 3.1
    • node 3.2
      • node 3.2.1

Searching From...Finds...
invisible node 3.1(nothing)
node 3.2
  • node 3.2
    • node 3.2.1
node 3
  • node 3
    • node 3.2
      • node 3.2.1

Food for thought.

(Oh, one last thing. How can you search from an invisible node? Maybe that should "find" an error.)