Write the Friendly Manual

Rules and usability.

 Thumb up

18xx Rules Template and Style Guide

Jason B
flag msg tools
Microbadge: Dead Kennedys fanMicrobadge: Train GamerMicrobadge: Venture Bros. fanMicrobadge: Darts fanMicrobadge: MST3K fan
(This has been posted in a few places already, apologies for the spam if this is the third time you've seen this.)

I am excited to announce the existence of a project I have been working on for a while now. I call it "Jason's 18xx Rules Template and Style Guide," or RTSG for short. It is a document that aims to make the rules writing process easier. It does this in three ways:

1. It provides a bunch of generic rules text that anyone can freely make use of. Not sure how to phrase or describe something in your rulebook? Feel free to copy text from the RTSG and modify accordingly. Modification will almost certainly be necessary as the RTSG aims to be quite generic.

2. It includes a short style guide that discusses best practices regarding terminology and formatting.

3. It has a handful of writing tips aimed at people unfamiliar with technical writing.

The RTSG is based on my experiences working with All-Aboard Games: I have indexed the rules to nearly all of the games in print, and wrote the rules for several of them (and for a few upcoming titles).

Right now the RTSG exists as a Google Doc that can always be accessed from my website: https://www.jasonbegy.com/the-18xx-rtsg.html

The document itself provides a much more thorough introduction than this missive.

It is a living document that I will be expanding and improving upon as time allows. I had hoped to put a few more days' worth of work into the RTSG before launching, but I am starting a new job in a few days and I am not sure how much time I will have to work on it in the coming weeks and I wanted to get it out the door, as it were.

I'm happy to answer questions about it, but please read the introductory text first.

I hope you find it useful!

Twitter Facebook
Mon Mar 28, 2022 6:32 pm
Post Rolls
  • [+] Dice rolls
 Thumb up

Rules Deep-Dive: Readability, Referability, Changeability

Jason B
flag msg tools
Microbadge: Dead Kennedys fanMicrobadge: Train GamerMicrobadge: Venture Bros. fanMicrobadge: Darts fanMicrobadge: MST3K fan
One of the least popular aspects of board gaming is rulebooks. Few people like to read them (as evidenced by the popularity of instructional videos), even fewer like to write them (as evidenced by the number of poor rulebooks), and these two trends probably reinforce each other. They are, however, a necessity: after all, if nobody can figure out your rules, nobody is going to play your game!

This article is for anyone who writes rulebooks in any game genre, although I will be pulling examples from 18xx. I use the word “rulebook” intentionally to refer to the kind of long rules documents typical of 18xx and wargames, although much of this article is applicable to shorter documents.

Specifically, this article discusses how to use sections and section numbering effectively in your rulebooks by analyzing specific examples from three 18xx games, however, the emphasis here is more on providing tools to think with than on absolute rules or best practices. Some of the things I will be discussing come down to judgment calls or individual preference, but after reading this you will be better able to think through how to structure your own rulebooks.

The rulebooks I will be discussing are for 1761, 1822, and 1837, all available from All-Aboard Games. I indexed the rules for the first two (among many others), and have been working on a rewrite of the 1837 rules with Scott Petersen as well. I have selected these rulebooks for analysis because they were all written by different people, have different strengths and weaknesses, and use section numbering differently. Each rulebook will be evaluated and analyzed in terms of its readability, referability, and changeability, all of which are defined in the next section.

Although I will at times be critiquing these rulebooks, I want to state clearly that the intention here is not to attack or indict anyone. Rules writing is very difficult, and most rulebooks are written by game designers who didn’t get into designing games so they could write rules! The games discussed here are all excellent titles, and my critiques of their rulebooks should in no way discourage anyone from checking them out.

Full disclosure: I received a one-time small amount of store credit from All-Aboard Games for each of these indexes as a token thank you. I receive no compensation based on sales of these games, or any other All-Aboard Games.

Who Uses Rulebooks? Readability versus Referability
It is useful to think of rulebook users as falling into two categories: readers and referrers. Readers read the rulebook straight-through, and they do it in order to learn how the game is played. They may be reading it for the first time, or reading it again to refresh their memory. They might be reading the rules because they will be playing the game soon, or maybe just out of curiosity. But their goal is to attain a holistic understanding of how to play the game that is sufficient for play. The “readability” of a rulebook refers to how well it supports this usage.

Referrers have a question about the game that they are trying to answer. They likely already have a broad idea of how to play, but they need specific information. When a player picks-up the rulebook to answer a query in the middle of the game, they are using the rules as a referrer, and this is probably the most common use of 18xx rulebooks. The “referability” of a rulebook refers to how well it supports this usage.

(It should be clear that what determines the category is the current use of the rulebook, and we all naturally go back and forth between these categories, depending on the context.)

An effective rulebook, then, is one that caters to both of these uses simultaneously. Readers must be able to learn the game from the rulebook, and referrers must be able to answer questions about the game as easily as possible.

Nowadays, it practically goes without saying that rulebooks can live two lives: as physical objects shipped in the box, and as “living” rulebooks available for download.

Naturally, one of the benefits of the latter form is that it can easily be edited and improved. There are many reasons for doing this, from fixing typos or adding helpful clarifications all the way to changing the rules of the game.

“Changeability” refers to how well a rulebook supports this. Rules can be structured in a way that supports edits and changes, which is particularly useful with the type of complex games I am discussing here.

On Indexing Rulebooks
Having an index in your rulebook makes life much easier for the referrer (who is, do not forget, your player and your customer). Instead of flipping through pages and skimreading (which is highly error-prone; I myself have made more than one rules mistake this way), they can use the index to go right to the relevant section(s). Just by indexing your rulebook you can greatly increase its referability and save your players a lot of headaches.

As a professional indexer I often wish my rulebooks had indexes. For instance, I can never remember where Priority Deal goes after the opening auction. I always have to hunt for that piece of information, and it is never in the same place.

When I index 18xx rulebooks, I index not to the page, but to the section number. By this I mean that the index entries point to the section that the subject is in, not the page as in most book indexes. There are three reasons for this. First, sections are almost always shorter than a page, and so indexing to section number is more precise. Second, this system supports the changeability of the rulebook, because it is unlikely that edits will alter section numbering, whereas the pagination may very well change--correcting an index due to a pagination shift is an indexer’s nightmare. Even if a new section is added, as long as it has a new number it is easy to add that into an index. Lastly, there is almost always a table of contents pointing to page numbers. Indexing to section numbers helps the index work alongside the table of contents by giving the reader another set of access points.

Of course, this means that how a rulebook is structured has a big impact on how the index turns-out, and consequently, how useful the rules are to referrers.

Comparative Analyses
The following sections analyze the use of sections and section numbering in the rulebooks for 1761, 1822, and 1837, and show how this affects their readability, referability and changeability. You do not need to be familiar with these games to follow the discussions, but you may find it helpful to download their respective rulebooks to follow along; this is not necessary, however.

Because the goal of this article is to provide some insight into how to think about using section numbers, the following analyses often include multiple perspectives, and they do not always agree with each other. As indexer Fred Liese likes to say, "there are no rules, only contexts." The same is true of writing rules.

1761 (Rulebook version 1.0)
In terms of its overall structure, the 1761 rulebook has a small number of sections. Looking through the rules, we can see that they only go down one level. For instance, operating rounds are covered in section 11, which is further subdivided into “routes” (section 11.1), laying track (section 11.2), and so on. Section headings are frequent enough that a reader won’t get lost, but not so frequent as to interrupt the reading process. The information is also provided in a logical order, making for a very readable rulebook.

In terms of referability, there are places where deeper section levels might help. Consider the second-to-last index entry, on page 15: “track, laying and upgrading, 11.2.” What this entry shows is that all of the rules covering laying and upgrading track tiles are in section 11.2. However, this section contains several paragraphs amounting to around half a page of text. If a referrer has a question about whether tile upgrades are permissive or semi-restrictive, for example, they will need to read a bit to answer their question. To be fair, this is not a lot of text, but in the middle of a game session referrers need answers as quickly as possible to avoid holding up the game.

That said, it is also important to consider consistency and parallelism throughout the text. Although section 11.2 would have greater referability if broken down into 11.2.1 (covering laying track) and 11.2.2 (covering upgrades), there really aren’t any other sections that could be broken-down further. Subdividing section 11.2 would thus create inconsistency in the rulebook, which risks confusing users, and is a good argument against doing so.

Another advantage of this broad structure is that it supports changeability. For example, if the designer or publisher decided they wanted to add some clarifications, or tweak some rules, the headings are general enough to support this with minimal difficulty. Changes kept under existing headings would not affect the index, and new sections could easily be added and then indexed. The only real effect would be a need to update the table of contents, which can be done automatically.

As an aside, this rulebook has a nice example of how useful an index can be. Section 11.5, “Calculate Earnings” has a lot of information about routes that is not covered in section 11.1, “Routes.” Given the order in which information is presented in this rulebook this makes sense, as trying to cover how routes are valued in the earlier section would be confusing. (Many rulebooks make the mistake of trying to put too much information upfront, which is not the case here.) But a referrer with a question on routes who goes to the table of contents might miss all of the information in 11.5. Naturally, the index entry for “routes” points to both sections, thereby enhancing the overall referability.

1822 (Living Rules version 2.0)
The rules for 1822, on the other hand, are quite different. Section headings are still in two levels, but every rule, which can be a paragraph or sentence, has a unique identifying number, which is often at the third level. For example, section 4 is titled “stock rounds,” which is followed by section 4.1, “introduction,” beneath which are three paragraphs numbered 4.1.1, 4.1.2, and 4.1.3. This pattern is repeated throughout the rulebook.

The advantage of this method is its accuracy: individual rules can be referenced in discussions and indexing is very precise because entries can point to the exact rules covering the topic. The referability of this rulebook is generally quite high. However, it does make the rules a bit harder to read through, because the proliferation of bolded section numbers is distracting to the eye and interrupts the flow of reading.

On the other hand, while this format allows for a very precise index, the index itself can be hard to read. For instance, under the entry “minor companies,” there is a subentry as follows: “initial share values, 3.3.4–3.3.5, 4.4.1, 4.10.1–4.10.2.” When grouped together like this, three-level section numbers are challenging to read. Sometimes this can be overcome by indexing differently, but that often entails wordier entries that will also take-up more space.

This example also demonstrates a little-acknowledged benefit of indexing: it reveals things about your rulebook that you might not have realized, and in turn suggests editing strategies. This entry shows that minor company initial share values are discussed in five separate sections, and so it might make more sense to use a single section to discuss the topic. Then in-text references to that section could be added where relevant, thereby potentially saving some space in the rulebook and keeping the information well-organized.

However, the downside to this method is that the user may find themselves constantly flipping around through the rules in pursuit of these references. Repeating information in all the places that it is relevant uses more space, but it makes things easier on your user. In indexing this is known as “double-posting,” and is standard practice. For example, in the 1822 index, “London” has its own main entry with five subentries, but London is also a subentry under several other main entries. This increases the odds that the referrer will find what they are looking for.

The choice between these two methods is largely a stylistic preference, however, and one of the advantages of having an index is that information that has been scattered throughout the rulebook is neatly tied together.

Another interesting thing about the 1822 rules is the small number of main sections: there are only six level-one headings covering the meat of the rules. As a result, the individual rule numbers tend to get quite long and hard to read, like “5.12.11.” Naturally this becomes easier with practice, but for users who are used to standard decimal numbers it looks odd and takes a moment to comprehend. Having a larger number of level-one headings would help mitigate this problem by spreading everything out.

From an information hierarchy perspective, however, this structure makes a lot of sense: most of the rules cover things that happen in stock rounds or operating rounds, and so most of the rules should be under these two sections. The table of contents shows this to be the case: the core of the rules are on pages 2 to 24. Of these, stock rounds are covered on 10 to 14, and operating rounds from 14 to 24. Long section numbers are a natural side-effect of this method because everything is grouped together.

One way to address the number readability problem would be to create more main sections, trading-off the accuracy of the information hierarchy for usability. For instance, “first turn housekeeping,” section 5.6, could be moved up a level to its own main section. Although it is technically part of the operating rounds, it won’t happen in every round, unlike most of the other rules under ORs. Further, because these rules are unusual (in 18xx terms), it is likely that players will be referring to them often, and making them into a top-level section would also make them more visible.

As noted, such a change disrupts the information hierarchy that has been established. Neither method is strictly better, but these are important things to consider when structuring your rules. If the rules were edited such that section 5.6 became its own first-level section, it would then make sense to move other, similar subsections to the top level, for consistency's sake. Section 5.18, "Minor Company Acquisitions," would be a good candidate for the same reason that section 5.6 is: these rules are likely to be referred to often because they will not come up in every operating round.

What if these rules need to be modified later? A dense numbering system like this, as opposed to 1761’s, makes changes harder. If a rule has to be added in the middle of a section, it can have a cascading effect on the following rules, thereby requiring updates to the section numbers in the text and corrections in the index, which introduces the possibility of errors creeping-in. Incidentally, the version 2.0 rules illustrate this perfectly by way of the 1822+ expansion. Rules covering this expansion are formatted in red text, and you can see that they are often (but not always!) added into existing sections. Sections such as 2.1.7 and 5.18.8 are exceptions, and required adjustment of the following section numbers.

1837 (Rulebook version 3.0 draft) - Link
The rules to 1837 have a bit of a storied history: the rules in the original, German-only version of the game were just a list of differences from 1835, much like how Winsome’s 18xx games come with rules differences from 1830. This original document was translated and expanded upon at various times by Stuart Dagger, Paul Work, and John Webley, resulting in version 2.0 of the rules.

When I received my copy of the game in 2018, I saw that the rulebook could use some further help, and I contacted Scott Peterson about it. This lead to a large collaborative restructuring and rewriting effort; the current version is linked above.

From the outset, I decided that I wanted to strike a balance in section numbering: three levels for greater referrability, but not to the point that every rule is individually numbered. 1837 is similar to 1822 in that there are a lot of rules (more so than in 1761), and many of them are unusual, so the rulebook benefits from having a third heading level.

For instance, the rules covering the city of Bozen, Italy and Bosnia-Herzegovina are all unusual, in 18xx terms, but are also too short to warrant being placed at the top level. As such, they were put into their own third-level sections (10.4.2, 10.3.3 and 10.3.4, respectively). This helps the readability because it signals to the reader that these sections will be covering lots of particular exceptions, and helps the referability by collecting these rules into easy-to-find locations, which in turn makes for precise indexing.

Keeping the section numbering broad was also important for changeability. The currently available version has been online for public feedback for over a year (as of the time of this writing), which has been invaluable. This has inevitably meant numerous changes, and the section numbering allows us to make improvements in response to feedback without causing problems elsewhere in the document.

The current version also uses a large number of top-level sections, 14 in all (although this ended-up being fewer than in version 2.0, which hardly used any subheadings. For instance, although forming the national railways happens in the ORs, putting these rules under “operating rounds” adds a lot of rules to that section which are not often used; this is analogous to the "first turn housekeeping" example in 1822. The same goes for the coal company exchanges. These sections were placed at the end of the rulebook because players will not need to refer to them in most ORs, and they are easier to find when needed.

Another way of supporting rulebook readability and referability is the use of "see" references which point the user to a related section elsewhere in the rulebook. This is useful for readers because if they have a question or do not understand something as they are reading, the "see" reference signals that the concepts are explained more fully elsewhere. This helps avoid overly frontloading rules. For referrers, "see" references increase the odds that they will find what they are looking for.

For example, section 7, "Corporate Entities," contains many "see" references to other sections that give fuller descriptions of the different types of companies, signalling to the reader that more rules will be forthcoming. But it also supports referability: suppose that the user has a question about minor companies. They look up "minor companies" in the index, and they see the first entry: "about, 7.2." Section 7.2 gives an overview of how minor companies work in this game, and it also has a "see" reference to section 10.7.2, which specifically covers how minor companies operate. If section 7.2 did not answer their question, they already have an idea of where to look next, without having to turn back to the index.

The current version of the rules is not yet indexed, as it is still being tweaked here and there. However, if I were to index it at this moment, it would look something like this:

track tiles, laying, 10.3
--in Bosnia-Herzegovina, 10.3.3
--in Italy, 10.3.4
--and mountain railways, 10.3.2
--terrain costs, 10.3.1

track tiles, upgrading, 10.4
--Bozen, 10.4.2
--cities, 10.4.1
--towns, 10.4.3

In terms of usability, this hypothetical index is easier to read than in 1822, but more precise than 1761. Even when referring to third-level sections these entries are easy to read, because at the third level the rules sections cover more material than one or two rules, and so there is no need to use spans of difficult-to-read section numbers in the index. At the same time, the use of three levels of headings enables a more precise index than just two, greatly enhancing the referability of the rulebook. 

Closing Thoughts
The structure of a rulebook has a direct impact on its readability, referability and changeability, all of which affect your players' experience of your game. As such, it is important to think about all of them throughout the writing and editing process. However, writing rules is more art than science, and what is right for one rulebook may not be right for another. But by thinking through the issues and examples discussed above, you can hone-in on the best structure for your rulebooks. A well-structured rulebook goes a long way towards helping your players get into your game, and stay there.
Twitter Facebook
Wed Feb 26, 2020 2:31 pm
Post Rolls
  • [+] Dice rolls