liveBook · Manning

Readability

As explained in Effective Behavior-Driven Development

The ease with which written scenario text can be read and understood.

Readable scenarios make the intended behavior clear to the people who use them as specifications. Favor clarity over making steps easier to automate or eliminating every repetition. section 9.5 section 9.6

Keep scenario text easy to follow:

  • Use pronouns when their meaning is clear; repeat a noun when a pronoun could refer to more than one person. section 9.5
  • Keep data and examples tables small enough for the whole scenario to fit on one laptop screen; align table separators. section 8.4.5
  • State exceptional context explicitly, but leave out context readers can reasonably treat as implicit. section 9.9
  • Prefer consistent, readable phrasing to forcing step reuse, and use Background cautiously when shared context is easy to overlook. section 9.11 section 9.6

When a pronoun obscures meaning

In “a manager processing a valid request to cancel their restriction” followed by “they override the restriction,” it is unclear whether “they” means the manager or the customer. Naming the actor again can make the behavior clearer. section 9.5

Listing 9.13 Electric kettle – context steps not essential
Scenario: Kettle boils water
  Given the electricity supply is live
  And the fuse is not blown
  And the kettle has water
  When I turn the kettle on
  Then the water should boil

Scenario: Kettle is protected from burn-out
  Given the electricity supply is live
  And the fuse is not blown
  And the kettle is empty
  When I turn the kettle on
  Then the burn-out protection should engage

Compare the kettle scenarios with their repeated context against versions that omit context readers can infer. section 9.9

How Effective Behavior-Driven Development covers it

How deep it goes
Gives practical guidance on pronouns, tables, context, reuse, and Background, without detailing automation implementation.
Examples
Contrasts clear and ambiguous pronouns, oversized tables, and kettle scenarios with explicit or implicit context.
What you can do after
Apply readability priorities when phrasing scenario steps, choosing context, and deciding whether to reuse steps.
How it connects
Connects readability with Gherkin, scenarios, step reusability, and Background.

Also explained in

Compare how 2 books explain readability →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Effective Behavior-Driven Development. The section links point to the parts of the book it draws on.