I've started playing Blades in the Dark recently and it's amazing! So I thought I'd dedicate some time to dissecting the most inconsequential part of my experience, because it happens to be of the most relevant to writing board games.
The Blades in the Dark book gives the image above (or something similar to it) as part of an example sheet on how skills work. This is used for a few examples, but the one that stuck out was the one illustrating that when you try to resist something you resist using a skill category - rather than a skill. So you never roll "Resist on Skirmish" you instead roll "Resist on Prowess".
In this case two dice.
It turned out that a couple of us had skimmed the rules and nobody had read them in detail. We'd both seen that example - that setup means a person has two dice for a prowess roll - and thought that we knew the rule.
It meant that your prowess roll is equal to your best prowess skill.
It meant that your prowess roll is equal to the number of prowess skills you're trained in.
This encapsulates a very straightforward lesson about writing examples for rulebooks: As well as bearing in mind what the rule *is* and showing it clearly, you need to bear in mind what the rule *isn't* (but might be) and avoid creating ambiguity.
What other lessons might we take from rulebook examples?
I often find a rule-example pair like this early in the rulebook:
"To roll an attribute, take a number of D6s equal to the attribute, roll them and add the two highest dice together.
Example: Gurk has a strength of four and attacks an orc. His player takes 4D6 and rolls them getting 2, 3, 5 and 5. This makes his roll 10, he delivers a critical hit and the orc takes 3 damage."
This sort of example tends to raise more questions than answers. It is demonstrating the rule it's associated with, but it's also demonstrating two other rules that haven't been introduced yet.
Why is it a critical hit? Because the total was double figures? Because it exceeded a target by some amount? Because the numbers used were a pair?
Why did the orc take 3 damage? Why not 2 or 4? Did the attribute roll decide that somehow? 3 was the highest number that didn't get used.
Which gives us a second thing to bear in mind: An example should only invoke rules that have been introduced in the rulebook before the example is given.
If someone has only has examples they don't actually know the rule. So if a book contains something like:
"In this phase you prepare your buildings, so for example you may place the granary face down on the table."
Then the player actually has no idea what the rule is, though they might think they do. They know they *can* place a granary, but there are lots of things they don't know:
Can they place something they can't afford at the moment?
Can they place a second card and choose to build multiple things?
Can they place face up if they want to?
Do they have to place anything at all if they don't want to?
Learning rules this way is a bit like playing with a magic eight ball. You get a bunch of unconnected statements and if you're lucky you can draw some sort of narrative between them, but if you learn what you were trying to it's more luck than judgement.
The obvious lesson from this is that your example needs to be an example of a rule that you've expressed, rather than an alternative to expressing the rule in the first place.
The slightly less obvious lesson is that this only helps if the reader actually reads that rule before the example There's a graphic design problem in the way that a person's eye is lead around the page by paragraph formatting, coloured boxes and the like. There's also a rules writing issue in that people will more easily remember the first or last statement made in a given paragraph or section.
But we're moving away from examples to general rules writing, so let's just consider this: The presentation of an example should encourage a reader to examine it after the rule it is an example for.
So we've talked about a lot of potential pitfalls and problems with examples, so to flip the question: Why bother? What makes a good example?
A good example will help a person to understand a rule and resolve any questions they have about it. As a designer it's not possible to predict every question a person might possibly have about how to play a game, but having a worked example makes it likely that a person can see the answer to their question without having to predict what it is.
Generating that sort of example isn't always easy, but having gone through the playtesting process will help. Considering some of the most common mistakes that are made by first time players and writing examples of the form "Here is the setup for the situation that most commonly leads to a mistake and here is the correct play."
Also avoiding talking about not just what happens, but why it must happen. For instance I've recently updated a SatW example to
"...The item that Amy receives from Phil is the NO/DK fanart, which sister America wants. As it will satisfy her character she must immediately place this item on America before the game continues..."
Stating only that the item is played, while technically correct, produces a less useful example, because it's less obvious whether Amy could have chosen not to play it or even if a person must play every item they draw right away.
So to make a list:
Examples need to consider rules that may be, as well as rules that are.
They should only reference rules that have been mentioned so far.
An example can never be a replacement for a rule.
If an example is complicated, it should show "why" as well as "what"
There's a lot more that goes into selecting and writing good examples, but that's a good starting point. If nothing else it serves as an example for the sorts of things you might think about Happy gaming.