Choosing the right audience for your living documentation

©Manning Publications Co. We welcome reader comments about anything in the manuscript - other than typos and

188

Among the many useful purposes it has, a documentation is also a teaching tool. By documenting features, user stories, or code, you’re teaching your readers about everything they need to know in order to get to work. It seems logical, then, to draw some inspirations for creating better living documentations from the realm of education.

But do you remember how in school everybody seemed to have a bit different pace of learning? For example, students who were curious at heart might have already known some portions of the reading material from other sources they have read before. That’s because, even though we may come from similar backgrounds, everybody’s a little bit different. Yet, textbooks are the same for everyone in class.

To do their jobs well, authors who write coursebooks must first establish a baseline of knowledge and skills every student must possess in order to successfully complete the course. Only if they do so, they will know that these skills have to be covered in detail, making the main body of the text. If they didn’t, results would be catastrophic. To understand why, we can examine a simple mental experiment. Let’s take an average student in an average class. Being average means that half of the students are worse than our chosen student and half of them are better—which means that if the textbook was written for the average student, at least half of the kids would find it more or less difficult to read.

That’s why coursebooks' authors spend a lot of time thinking about the right

—the MQR—and write as if for that person only, keeping in minimally qualified reader

mind what that person can and cannot know.

NOTE

NOTE Minimally qualified readerMinimally qualified reader

A minimally qualified reader is a persona of a typical student with the basic skills needed to benefit from the teaching. Knowing your MQR means understanding what that person already knows, and teaching what that person doesn’t know yet. Defining the reader is an essential part of making good, useful living documentation.

Just like students, people in teams and organizations are not uniform, too. For example, let’s consider a junior-level engineer, straight out of college, who joined the team a few months ago, a mid-level designer, and a senior tester who has been around forever and knows the ins and outs of the system. They all have different work experiences and skills.

How can we write documentation for all of them?

Moreover, each of the professions—the engineer, the designer, and the tester—already have their own documentations. Engineers can document their work with code comments or architecture diagrams. Analysts, too, use diagrams; they can also write 7.5.1 Who’s a minimally qualified reader?

7.5.2 Finding the perfect MQR in your organization

189

user stories or use cases. Designers build design systems that explain their decisions and make sure that elements and styles are used consistently. Testers, too, document their work by building matrices for manual tests, refining acceptance criteria, and writing bugs and errors down by creating regressions tests.

But engineers write documentation for other engineers; designers write for other designers; testers write for other testers. Yet, living documentation is documentation that can and should be written by all of the team members. The content is different, too.

Gherkin scenarios talk about business features, the business domain, and high-level examples, which may be new and difficult to understand to the delivery team regardless of their role and technical skill.

So living documentation can be written by all of the team members as well aswritten all of the team members. But if everyone on the team is the audience, how do you for

actually choose the MQR? In section 7.3.1, I told you that it’s a good practice to write as if for that person only, keeping in mind what that person can and cannot know. In my experience, it’s even best to simply choose an actual living person in your organization as the MQR, because you can always run your scenarios past that person, watch the reaction, and then revise accordingly.

How do you spot that person, though? What are the criteria you should look for?

The MQR should

be experienced enough to be confident in their craft, so we don’t feel the urge to explain any universal solutions, either in design or technology

have at least some technical understanding due to working with a technical team but programming skills at not necessary

be new to the business domain, so it’s expected that the MQR doesn’t know the terminology, business-related concepts, industry standards and regulations, company workflows, or competitive advantages

TIP

TIP The MQR should be a mid-level new hire who knows the basics of their craft, but doesn’t understand the business domain of the project yet. A basic, solid programmer, designer, analyst, or tester—maybe a couple of years on the job.

NOTE

NOTE Exercise 3Exercise 3

Find a good MQR in your organization. Can you think of anyone? It can even be a coworker sitting in the desk next to you.

Thinking about the MQR, you can also consider creating a list of prerequisites to explicitly define the areas of knowledge your team members have to already know before coming to work with the specification suite. Creating such a list is usually unnecessary when dealing with easier business domains that the team thinks they know well. But sometimes such a list can be of help in projects that are more difficult.

©Manning Publications Co. We welcome reader comments about anything in the manuscript - other than typos and

190

NOTE

NOTE Exercise 4Exercise 4

Make a list of 3-5 domain prerequisites for your team in your latest project. Are you sure the MQR will know all of them?

When dealing with any particular feature, you may want to think about the takeaways you want your future readers to understand. Defining the takeaways up front will let you decide what the best method for teaching the reader each skill is. Some takeaways will require their own scenarios; some will work well as examples within other scenarios;

some just need a short note in the specification brief or the scenario briefs.

NOTE

NOTE Exercise 5Exercise 5

Make a list of takeaways for the screening feature from listing 7.2.

Exercise 1 Create a short definition that explains what a Scenario Outlineis.

A Scenario Outlineis a scenario that can take multiple examples at once.

Exercise 2 Create a definition by example that will define the concept of Gherkin’s keywords like Given When, , or Then.

A Gherkin keyword is any special word like Given When Then But And Scenario, , , , , , , and so on. Keywords are always placed at the beginning of new lines.

Feature

Exercise 3 Find a good MQR in your organization.

This is a funny exercise to provide an answer for, but I’ll try anyway. A good MQR in my last medium-sized project was Mark, a great programmer who recently joined the company but had no idea about the products we were working with, because we were an agency and had multiple rotating clients. Mark, if you’re reading this—hello!

Exercise 4 Make a list of 3-5 domain prerequisites for your team in your latest project.

What property management is

The differences between the renting process in the countries we support Why it is difficult to find an apartment as a tenant in most markets The details of signing a lease

Exercise 5 Make a list of takeaways for the screening feature from listing 7.2.

7.6 Exercises

191

A reader should know what the screening process is A reader should know what we screen for at this moment A reader should know what we do not screen for and why A reader should know what the credit score is

A reader should know when a candidate is accepted

Living documentation is documentation that changes along with the system it describes Gherkin can document the business domain for people unfamiliar with it or document the delivery team’s decision-making process for future reference

Lexical definition explain domain concepts in specifications briefs and scenario briefs A definition by example is a list naming the objects that belong to the set being defined A single domain concept—such as an actor, an action, or a state—always should be called the same way throughout the specification suite to avoid confusion and misunderstandings

Specification briefs and scenario briefs can also be used to document various decisions made during the development process as a future reference, including business context, warnings, or maintenance notes

Creating Gherkin documentation is an iterative process. It starts during team workshops and the documentation keeps being refined as the feature evolves

A minimally qualified reader (MQR) is a persona of a person in your organization with the basic skills needed to benefit from the documentation on their own

A good MQR can be a mid-level new hire who knows the basics of their craft, but doesn’t understand the business domain of the project yet

7.7 Summary

©Manning Publications Co. We welcome reader comments about anything in the manuscript - other than typos and

192

8

This chapter covers

This chapter is the first chapter in the four-part series about managing large specification