Use a descriptive title and explain the goal using a short paragraph

If a speciication contains only inputs and expected outputs, anyone who reads that document will have to reconstruct the business rule from the examples.

It’s crucial to choose a descriptive title for a speciication. The title should summarize the intent. Think about what you’d type into Google’s search box to look for a speciication if it were somewhere on the web, and use that as the title. This will make it easy for readers to discover the appropriate speciication when

searching for an explanation of a piece of functionality.

A reader also needs to understand the structure of the speciication and its context. Explain the goal of the speciication and the structure of examples in a few words—no more than a short

paragraph—and put it in a header. A good trick for writing the description is to write only the examples irst and then try to explain them to someone else. Capture what you said while explaining the examples, and put that in the header of the speciication.

Show and keep quiet

When: Someone is working on speciications alone

In order to: Check whether a speciication is self-explanatory

To ensure that a speciication is really self-explanatory, ask the other person to explain what they understood and see if that matches your intention.

If I show a speciication to someone and I ind myself having to explain it, I write down the explanation and put it in the header. Explaining the examples often leads me to use more meaningful names or insert comments to make the examples easier to understand.