I kind of like Root's approach, just make three separate rulebooks. One quickstart guide, one "normal" rulebook, and one "law" type rulebook laying out everything in almost procedural style with clear and consistent definitions etc. Many games could benefit from that.
Most modern boardgames do something like that (although typically in a single book with multiple sections).
The standard seems to be to start with a setup/quick start guide that walks you through the initial setup and the in-order game loop.
Then have a reference section that goes through all of the specific mechanics (e.g., a deckbuilder might have "then play a card from your hand" in the quick start, and the reference section would go through the various cards available).
Then at the end is a FAQ, that is mostly just all of the rule lawyer stuff.
Modern games also tend to be better at not needing new players to refer to the rulebook as they used to. Nowadays, you almost always get some form of a cheat sheet card that explains the core game loop, and many rules will be encoded in some way on the game elements themselves.
Now that I think about it, technical writing classes should really take field trips to game stores. There is a lot of impressive that goes into communicating how to play that most people never notice.
> Most modern boardgames do something like that (although typically in a single book with multiple sections).
As a member of a boardgame club having played to approximately a hundred of less-than-two-years-old games[1] over the past year and a half, I can assure you most boardgames don't, even modern ones.
[1] yes, there are that many games. A few years back there were approximately six hundreds new games being released in a year, for the French market alone (granted it's one of the most dynamic), and I heard it more than doubled after Covid so I don't know where we're at right now.
But many are just variations of a gameplay: Splendor and Century are the same thing (one of some limited actions per turn, most things visible, you buy something to generate resources to buy points). Most cooperative game too: it's either unlock like (escape room) or forbidden island (some objectives and a way to increase the pressure on players).
> Modern games also tend to be better at not needing new players to refer to the rulebook as they used to
I wonder if those new players have thousands of sessions of play under their belt or if they are truly new players or with only a few games of experience.
I don't listen much to the explanation of a new game because there are usually too many rules to remember, they resemble parts of some other games (like learning Python when you know Ruby) and I ask questions when I'm playing and (sorry if somebody feels bad about this:) these are not chess or go or backgammon, I'm not expected to study to become good and play thousands of games of them, they are all casual games to me.
All I need to have a decent first game and not score last is identifying a way to score points and play along that line. If I play that game again I will do better (maybe.) If I don't play it anymore it doesn't matter if I invested my attention into its rules.
The Fate books (at least several of them) are also free to download, with some Creative Commons license or similar, so you can read the rules without having to buy anything if you do not want to.
One war-game I played came with two rule books, which was incredibly helpful for learning to play - each player could read his own copy.
But single-page "QuickStart" rules for each player (which later serve as a reference) and a main rulebook can work well, also.
The problem with this is it can result in a bunch of "special cases" not being known about until later; IIRC we had this problem with Agricola and it wasn't until the fourth or fifth play through that we didn't identify a rule we had been mistaken about during play. That game's especially bad since it has so many possible interactions that could be A then B or B then A.
If you have fun isn't that the point. Ideally games should be a here are the simplified rules so you can have fun fast. Then here are the full rules so you can play a much more complex and fun game. Of course pulling that off is hard.
You're not going to learn a full complex ruleset in one sitting.Having a one page quick start of the game structure, allows you to get a feel for it before coming back for a deep dive.
Your brain has a foundation to build on when you read the ful complex rules - it wont feel like your brain is maxing out at 100%.
This is addressed in TFA. In many cases, attempts to create a simplified version of a game just teach bad habits; strategies that work in the simplified game might be not just suboptimal when the full set of options is available, but actively counterproductive.
But I dare say many fans of "heavier" games - especially ones with more of a simulationist bent - would disagree that having fun is sufficient.
Agricola is pretty old. Many of the older euros that were translated to English are shocking. And the way information is conveyed is noticeably worse than a good modern euro.
The original Agricola rulebook is almost completely unusable and the only way to learn how to play back in the day was someone who already knew how to play teaching you - I presume in an unbroken oral tradition all the way back to Uwe Rosenberg.
In a typical wargame special case rules are numerous, but mostly expected and conforming to familiar design patterns (e.g. entering a map hexagon containing something special with a unit, depending on unit type and state, is going to cost some extra point of movement or end the move completely).
So they and can be looked up when needed (e.g. what units can move enough to cross this river this turn?) and promptly forgotten.
It is usually enough to study wargame rulebooks just enough to know general procedures and trust the simulation to be unsurprisingly realistic.
I have not encountered a wargame that shipped with two rulebooks in the box, but often the latest rulebook PDF is available as a free download, so when playing a large wargame we often have printed one copy for each player, or at least almost that many. It is always good to have a rulebook within reach.
It was rare, but appreciated. The full-color bound rulebook was almost always better than a PDF printout (though rarely the PDF would be a newer version).
I'm a little less than impressed by the presentation here. The idea that Divio is describing here is the Diataxis framework (https://diataxis.fr/), which "is the work of" (https://diataxis.fr/colophon/) Daniele Procida (https://vurt.eu/). Who, incidentally, is also giving the PyCon talk in the video on the page you linked (https://www.youtube.com/watch?v=t4vKPhjcMZg). But I don't see anything resembling attribution for the ideas. They aren't just common industry knowledge or "received wisdom". (And the "quote" from David Laing at the top isn't really accomplishing anything, either.)
I’m not that impressed with Diataxis, considering it is basically describing the approach of Django project’s docs—which (both docs and the aporoach) predate Diataxis by many years—without giving any credit that I know of.
Jacob Kaplan-Moss described[0] the approach in 2009 (he omitted the How To guides, but they are in fact part of Django docs for as long as the framework is widely used). If there was a person to credit for this, that would be him.
I don't think this is quite the same idea, and it isn't anywhere near as deeply elaborated, nor given a theoretical basis. Of course no concept on this scale just pops out of the ether fully formed - as I noted elsewhere, the dichotomy (tetrachotomy?) described by the Diataxis model bears a striking similarity to that in Kalb's model of experimental learning. But that's just it - Diataxis could claim that much more strongly as an ancestor than Kaplan-Moss' approach, which is simply proposing that multiple forms of documentation exist and should co-exist to complement each other, without proposing why or how.
Although this actually gets at a frustration I had with Johnson's essay. There's a section that presents research and examines the VSK model and Kalb's model, and in both cases finds: a) they're wrong, in the sense that they hypothesize different kinds of learners that don't exist; and b) they're useful, in the sense that they describe different kinds of stimuli that should exist in a learning environment. Not because they serve the needs of different students, but because they serve the needs to students at different times or in different conditions.
But instead of applying those lessons, Johnson basically uses the findings about VSK to dismiss critics, and spends dozens of pages re-deriving an approximation of Diataxis theory which would have flowed directly from mapping the Kalb model onto forms of technical writing (which, while not quite the same thing as "documentation", is good enough to get to the right conclusions).
It would omit what Johnson calls "lesson plans", but these seem to be basically just the source code for tutorials. And it would omit "textbooks", but I think a lot of these are bad anyway, for many of the same reasons that board game rulebooks are.
Thanks. I already had "something about Diataxis" somewhere on my blog agenda before the HN post, and between this and the rest of the comments and the article I feel like I have a lot more material now.
> I need a how-to right now and all I get is an explanation.
This isn't a reasonable expectation. Your current state of documentation may be very different from some-other-software's current state of documentation. There may (or may not) be commonalities across those states, but assuming the most conservative situation leaves you with no commonality and the author's only option is to write the explanation for you. From there, you have to think about what transformations you need to apply to your current state to get it to the desired state.
Contrast this with game rulebooks. There is a clear commonality: situations where none of the players know any of the rules. Therefore, the rulebook can easily be written assuming no knowledge of the current rules of the game. Players that know the rules of the game can either a) go make everyone coffee and avoid polluting the learning phase with information that stretches the patience of the folks reading the rulebook; or b) claim to the players that don't know the rules that the rulebook is useless and they can do a much better job explaining all the nuances much better than the person that designed the game.
Did you not read the link? The reference should be obvious. I'm giving the link too much credit calling it 'explanation' but it isn't even an example of what it advocates in any case.
It drives me crazy personally, I think Arcs abandoned this for good reason. Root has a major rules sprawl issue IMO. Many rules are spread throughout the cards, the "Learning to Play" guide, the "Law of Root", the player mats, etc. I don't actually think you can really learn the game unless you have the board and player mats right in front of you. Wehrle's predilection for thematic names with clearer/plainer synonyms I think makes this hard as well.
People who praise the game by saying "the board teaches you how to play" are technically correct, but I think this glosses over how difficult it is to internalize turn structure before sitting down to play the game.
That being said, it's not the worst game I've ever had to learn. That dubious distinction probably belongs to Wehrle's John Company (scowling at you "Events In India" rules).
> Root has a major rules sprawl issue IMO. Many rules are spread throughout the cards, the "Learning to Play" guide, the "Law of Root", the player mats, etc.
Every rule AFAIK is in the Law of Root. So just refer to that. Once you've played once you should never look at the Learn to Play again. The player mats are player aids to remind you of the rules. The fact that rules are duplicated there is a plus, not a minus.
Funny that you mention Root. I recently played this game for the first time with three other SWE friends (also their first times), and we all found the multiple sources of truth, each seeming to make the assumption that you have already read the others and occasionally referring you to them, thoroughly baffling -- to the point where we started to make joking comparisons to the kind of software documentation that has an Overview, a Quick Start, a Tutorial, an Introduction, a Beginner's Guide, a How To page, a User's Guide, a Getting Started page, a Specification, a Reference Manual... Looking at you, Maven plugins.
Then again, maybe it was just that we were all a teensy bit drunk.
I'm afraid I can't. In very general terms, I just remember the feeling that I got several times was similar to that of discovering that something that I had thought was a scalar quantity was in fact a vector. Un-thought-of dimensions just seemed to keep popping up.
Our bafflement was probably enhanced by not noticing the "Learn to Play" booklet initially. Then each of us trying to read a separate booklet, and disagreeing with the others about how to proceed, etc.
Non-games could also benefit from different books for different use cases.
I once bought some disk utility software because I had a bunch of files that had accidentally been deleted that I really needed to get back (they were not on backup yet because they were recently created) and was quite happy that in addition to the 200 page exhaustive manual there was also a small booklet whose cover said in big print something like "Read this first if you bought this because you are trying to recover a disk".
That booklet was placed so that it would be the first thing you would see when you opened the box and you'd have to remove it to get to the installation floppies.
I know that there used to be some oversights where things where missing from the Law (like how to distinguish immediate effects from permanent effects on cards based on whether the box is paper or stone) but all of them have been resolved by now.
