BoardGameGeek
The Hotness
Hotness Display

Rulebook Editing Style Guide

Microbadge: Button Shy fanMicrobadge: Fan of Stonemaier GamesMicrobadge: Rules EditorMicrobadge: I edit my posts in the quest for perfetcion.

Mike Lee

United States flag
 Editor
@curby
@curby
 (edited)
I've been dabbling in editing rulebooks and card text for board games, but I know that designers can't always afford to hire an editor for every prototype and small-scale project. However, even prototypes can benefit from great rulebooks, since they help everyone from playtesters to reviewers to potential publishers.

I wrote a free rulebook style guide for three reasons:
• to provide a useful resource for designers working on their own rules,
• to start conversations with writers, editors, and proofreaders about best practices, and
• to record the lessons learned from my own editing work.

The guide is long because it aims to be comprehensive, but you can start with the three important topics listed in the introduction, covering the principles of cognitive load, careful framing, and consistent templating. If you're reading on a computer or other large-screen device, I recommend using the live-scrolling outline at the left and jumping to topics of interest.

As an ever-learning student of language, I don't claim to have all the answers. My goal is to encourage thinking and discussion about issues that impact rulebooks. If you disagree with or find counterexamples for a recommended technique, please reach out and let me know!

If you're an editor, proofreader, or writer, we welcome you to join us at the Editor's Hangout Discord server. It's a great place to talk about language, bounce ideas off fellow editors, or get help with a particularly difficult phrasing issue.

Here's to better rules and happier players!

  • Tip with GeekGold

Microbadge: Crokinole fanMicrobadge: Gaia Project fanMicrobadge: I love Ra!Microbadge: The Estates fanMicrobadge: Super Mario World fan

Joe Farrell

United States flag
@Arcturian
@Arcturian
Very cool! Thanks for sharing this. I'd be interested in your thoughts on a couple of examples in the middle of the document.

Quote:
During the Encounter Phase, the active player may play an Encounter Card. If they cannot play a card, they must draw a card instead. They may not activate special abilities during this phase.
I find this kind of awkward, because the first sentence describes a choice, but the second sentence shifts to describing a consequence of what the player can do rather than what they chose to do. If I encountered this in a rulebook, I would wonder: if I can play a card but choose not to, must I draw a card? Reading the text literally suggests that the answer is "no," but the construction is confusing enough that I'd wonder if the author used the right words, and I'd ask for clarification.

Quote:
If a player has no Scientists, they may not research Technologies.
I mentally tripped over this one for a moment and I think it's because my brain wanted to assume that the antecedent of "they" was "Scientists" rather than "a player" because the former is plural. I'm fine with using "they" as a singular—I did it myself earlier in this post without even thinking about it—but I wonder if it might be best to use another construction in cases where there might be ambiguity due to number. What about "that player" in place of "they" in the example sentence? This topic might be worth discussing a little more.

  • Tip with GeekGold

@Nicolas Weiss

France flag
 (edited)
Joe Farrell @Arcturian
Quote:
If a player has no Scientists, they may not research Technologies.
[...] I wonder if it might be best to use another construction in cases where there might be ambiguity due to number. What about "that player" in place of "they" in the example sentence?
This fix adds almost no cognitive charge or sentence length and is IMO all upside. That's for instance how MTG cards are templated. (And that game has quickly had to develop high standards for consistent templating and shortening text, since most the rules are written on the components.)

external image

  • Tip with GeekGold

Microbadge: Star Wars fan - GreedoMicrobadge: University of South FloridaMicrobadge: ChristianMicrobadge: City of Heroes fanMicrobadge: LEGO fan

James Arias

United States flag
@crazybyzantine
@crazybyzantine
 (edited)
Good stuff! I see tons of threads on “bad” rulebooks, but I’ve only seen one other thread like this with best practices for a “good” rulebook (vs. just pointing at “this random game has a good rulebook”).

(Other thread is this one on “comprehensible rulebooks”: https://boardgamegeek.com/thread/2451509/invitation-online-d...)

Edit: On Triggers/Callouts, totally agree with breaking those out as a “subroutine”, but in my cheatsheets (not rulebooks, but game aids/summaries), I prefer to give the callout a specially-formatted title, and put the detail of the callout after the round/turn coverage vs. right after first usage. I think the way you describe it is appropriate for initial teaching/learning, but (just me) for midgame skimming/lookup, I prefer callouts to be outside the main rules body. Especially if the game has a crazy complex round/turn structure with multiple nested callouts like this cheatsheet for Dark, Darker, Darkest. But ... cheatsheet is different use case from rulebook . Love what you’ve done here.

Edit2: keyword formatting...huge pet peeve of mine when not done (e.g. in SWIA, no way to know that “place” was actually a keyword!). I capitalize mine, but agree with your readability impact.

Edit3: Round vs. Turn. I use these same as you, but sometimes I see games flip the definitions (like convention used in 70s/80s era like AD&D). For me players take Turns within an overall Round. There’s also a good thread somewhere on BGG with community discussion about good terms for complex hierarchy (if need more than just Round.Turn.Phase), though games with more than that maybe need to be simplified.

Edit4:
Quote:
The active player draws a card at the beginning of their turn.
Situations like this are challenging because it reads more smoothly as written, but mechanically reversing the condition and action are more “templatized”. ... “Active player at start of turn draws a card” for who, when, does what order.

  • Tip with GeekGold

Microbadge: Geek Regular

Cy

Belgium flag
 Designer
@CyBadger
@CyBadger
Wow, this is amazing!

I've recently started designing print-and-play games as a hobby, and for me writing rulebooks is one of the hardest parts of finalizing a game.

Thank you so much for making that guide, it really helps people like me who don't want to or can pay for an editor.

  • Tip with GeekGold

Microbadge: University of California - BerkeleyMicrobadge: War Stories: Red StormMicrobadge: 10 Year Geek VeteranMicrobadge: War Stories: Liberty RoadMicrobadge: Constantly thinking about game design

Michael Tan

United States flag
 Designer
@m3tan
@m3tan
Joe Farrell @Arcturian
I mentally tripped over this one for a moment and I think it's because my brain wanted to assume that the antecedent of "they" was "Scientists" rather than "a player" because the former is plural. I'm fine with using "they" as a singular—I did it myself earlier in this post without even thinking about it—but I wonder if it might be best to use another construction in cases where there might be ambiguity due to number. What about "that player" in place of "they" in the example sentence? This topic might be worth discussing a little more.
This is a HUGE pet peeve of mine. I'm all for gender equality/neutrality but not when it is at the expense of clarity. The single most important goal of a rulebook is clarity. The ability to use both a singular and plural pronoun to distinguish between the subject and an object is an extremely powerful grammatical tool. I use it all the time when I'm writing rules. I establish a subject that often has multiple adjectives or participle phrases i.e. "The active player's unit that is ready and activated". I'm not going to repeat that phase 12 times in the next 5 sentences, so that phrase is henceforth referred to simply as "it". Any objects take the plural form "they" and there is never any ambiguity.

  • Tip with GeekGold

Microbadge: WargamerMicrobadge: Trenches of Valor - To-Hit RollMicrobadge: BSD userMicrobadge: Facebook avoiderMicrobadge: Emacs user - it's a way of life...

Pelle

Sweden flag
 Designer
@pelni
@pelni
James Arias @crazybyzantine
Edit3: Round vs. Turn. I use these same as you, but sometimes I see games flip the definitions (like convention used in 70s/80s era like AD&D). For me players take Turns within an overall Round. There’s also a good thread somewhere on BGG with community discussion about good terms for complex hierarchy (if need more than just Round.Turn.Phase), though games.
Wargames (almost?) always still use the old standard of a Turn that is usually divided into (more or less identical) Player Turns. Sometimes the Turn is just divided into Phases, sometimes each Player Turn is divided into Phases, and when the Phases get too complex they are in turn sometimes divided into Steps. There are probably some variations on this, but at least the Turns and Player Turns tend to be used, and I must say are very difficult to misinterpret (unlike Rounds/Turns that could easily be used either way and still make sense).

  • Tip with GeekGold

Microbadge: Star Wars fan - GreedoMicrobadge: University of South FloridaMicrobadge: ChristianMicrobadge: City of Heroes fanMicrobadge: LEGO fan

James Arias

United States flag
@crazybyzantine
@crazybyzantine
 (edited)
Pelle @pelni
James Arias @crazybyzantine
Edit3: Round vs. Turn. I use these same as you, but sometimes I see games flip the definitions (like convention used in 70s/80s era like AD&D). For me players take Turns within an overall Round. There’s also a good thread somewhere on BGG with community discussion about good terms for complex hierarchy (if need more than just Round.Turn.Phase), though games.
Wargames (almost?) always still use the old standard of a Turn that is usually divided into (more or less identical) Player Turns. Sometimes the Turn is just divided into Phases, sometimes each Player Turn is divided into Phases, and when the Phases get too complex they are in turn sometimes divided into Steps. There are probably some variations on this, but at least the Turns and Player Turns tend to be used, and I must say are very difficult to misinterpret (unlike Rounds/Turns that could easily be used either way and still make sense).
Yeah, for me it’s in context of “take your Turn” and “we’ve made our way ‘Round the table once” 🙂.

Reichbusters and Sky Traders got complex here as in RB a “Turn” is Hero-does-something-then-Enemies-do-something (“Hero Turn” and “Enemy Turn” [sic]), with some start of Round / end of Round considerations. Sky Traders IIRC had everybody do their Turn, and then before next Round started, entered a different kind of game mode briefly.

  • Tip with GeekGold

Microbadge: Button Shy fanMicrobadge: Fan of Stonemaier GamesMicrobadge: Rules EditorMicrobadge: I edit my posts in the quest for perfetcion.

Mike Lee

United States flag
 Editor
@curby
@curby
 (edited)
Thank you all for the amazing feedback and suggestions. I'll be working through them over time and adding you to the acknowledgements. Please let me know if you don't want to be thanked by name in the guide.

Full disclosure: a lot of the examples were chosen off the top of my head to illustrate a specific technique and have other issues. Please continue to point out these problems (and alternate examples if you have them) so I can improve the examples and the guide overall.

Joe Farrell @Arcturian
Quote:
During the Encounter Phase, the active player may play an Encounter Card. If they cannot play a card,
I find this kind of awkward, because the first sentence describes a choice, but the second sentence shifts to describing a consequence of what the player can do rather than what they chose to do.
You're totally right. I just wanted a context in which I could cram all the words into one situation. It's perhaps a bit hamfisted. I might break it into different examples, but let me know if you have a simple fix.

EDIT: I reorganized this section with separate examples. Hope that's better!

Joe Farrell @Arcturian
Quote:
If a player has no Scientists, they may not research Technologies.
I mentally tripped over this one for a moment and I think it's because my brain wanted to assume that the antecedent of "they" was "Scientists" rather than "a player" because the former is plural.
Great point! I've changed the example and added your suggestion as a potential pitfall to be aware of.

  • Tip with GeekGold

Microbadge: Button Shy fanMicrobadge: Fan of Stonemaier GamesMicrobadge: Rules EditorMicrobadge: I edit my posts in the quest for perfetcion.

Mike Lee

United States flag
 Editor
@curby
@curby
James Arias @crazybyzantine
keyword formatting... I capitalize mine, but agree with your readability impact.

...

it reads more smoothly as written, but mechanically reversing the condition and action are more “templatized”.
Thanks for the kind words and commiseration! The "fun" challenges often involve competing desires. 😆

  • Tip with GeekGold

Microbadge: Button Shy fanMicrobadge: Fan of Stonemaier GamesMicrobadge: Rules EditorMicrobadge: I edit my posts in the quest for perfetcion.

Mike Lee

United States flag
 Editor
@curby
@curby
Pelle @pelni
and when the Phases get too complex they are in turn sometimes divided into Steps.
I totally forgot about steps. Thanks for the reminder. Added!

  • Tip with GeekGold

Microbadge: Truck DriverMicrobadge: Silver File UploaderMicrobadge: I never get all the rules right!Microbadge: Neurodiversity Pride representing the broad and varied spectrum of experiences of neurodiverse peopleMicrobadge: Writer

Dean Ray Johnson

@dreamshade
@dreamshade
I just found this link while working on my own style guide. I really dig the discussion of good grammar techniques here.

  • Tip with GeekGold