A living documentation system that contains technical automation concepts, such as the command to wait until a given time for a process to complete, is a signal for a team to revisit the design of the underlying software system. The need to use technical concepts in living documentation often points to problems with system design, such as reliability of asynchronous processes (see “Listen to your living documentation” at the end of this chapter).

Using technical language is acceptable only when the stakeholders are technical as well and can understand what’s going on in the technical language (such as SQL queries, DOM identiiers, and so on). Note that even if the stakeholders are technical, using such technical language tends to describe how something is tested rather than what the functionality is. Although such tests might initially be quicker to write, they might cause maintenance problems in the long term. See “Scripts aren’t speciications” in chapter 8 for more information.

Mike Vogel used DbFit, a database test script extension for FitNesse that I wrote, to describe acceptance tests in a project with technical stakeholders who could understand scripts. In hindsight, he thinks this was a mistake:

In the beginning they were happy because they could quickly use DbFit and not write custom ixtures, so they had automated tests from day one. Later on, as the complexity of the solution increased, there was no time in the release plan to go back and create test ixtures to make the tests simpler and more understandable and to make the system more testable. We ended up with too brittle, too complicated tests.

Living documentation should be consistent

Living documentation is probably the longest living artifact of a project. Technologies will come and go, code will be replaced with other code, but the living documentation system describes how the business works. We’ll add content to it over several months or years and we need to be able to understand it later. One of the biggest challenges for many teams was keeping the structure and the language of their living documentation consistent. Stuart Taylor explains it nicely:

188 Speciication by Example

For the most part, the steps were very similar, so we found that having a single step ile for the all of the stories that belonged to that one piece of business functionality was really better. Otherwise, even though they were one-liners, we had a lot of duplication.

The fact that a living documentation system is automated and connected directly to software ensures that the software model aligns with the business model. Because of that, evolving a language for the living documentation system is a great way to create and maintain the ubiquitous language (as discussed in chapter 8).

Base the speciication language on personas

When: Web projects

Some teams described user stories through personas, especially when developing websites. In those cases, the speciication language can come from the activities that different personas can perform.

The team at Iowa Student Loan aligned the language used in their speciications with personas. Tim Andersen said:

Instead of users as an amorphous blob, we talked about different people and what their motivations to use the system are, how they use the system, and what they want to get out of it. We put names on different people. Boris was a borrower. Carrie was a co-signer.

Personas helped us because they made us think about how the system needs to behave from the perspective of a user. There are a bunch of positive side effects of using personas that we didn’t anticipate—for example, personas were test helpers [automation components] that were able to interact with our system at a more appropriate entry point.

Personas don’t make as much sense for projects that have little user interaction. Based on the success of using personas on a previous project, Andersen tried to apply the same concept to a technical data processing system. He eventually gave up and changed the language to a process low model.

Data comes from multiple sources and is loaded into a phone system so people can make phone calls. The phone data is updated, and we send it back to the entities who sent it to us. It is a batch process. Nobody actually uses it; it just runs. Personas weren’t a good it. We tried to get tests deined with personas and we got blank stares from the businesspeople. So I deleted all my persona code, and we changed it to be process based using the Given-When-Then keywords. That made it a lot clearer, and it made more sense to everyone.

Evolving the ubiquitous language around the activities of user personas allows us to ensure that our understanding of what individual personas need is aligned with how they use the system. This drives the structure and language used in speciications and helps us make the documentation system consistent.

Collaborate on deining the language

When: Choosing not to run speciication workshops

Christian Hassa says that collaborating on a language was one of the biggest challenges for his team:

Building a domain language that was consistent and bound well was completely impossible without guidance. Testers wrote things that developers had to rephrase. Sometimes this was because the way testers were writing them down was unclear or not easy to bind [automate]. When the tester had written already a lot of things, we had to rephrase a lot of things. If we tried to bind [automate] the irst example immediately, we would notice that it was not easy to do.

It’s like doing pair programming compared to doing code reviews afterwards. If you do pair programming, the pair will tell you immediately if he thinks you are doing something wrong. If you do reviews, you say: Yes, next time I’ll do it differently, but this time let’s leave it like this.