Making a good reference document/training manual

This keeps coming up in other threads, directly or indirectly, and it almost certainly causes problems for new players regardless of whether they started with N3, Code One, or N4, so I thought it might help to stick the topic in its own thread. This isn't a question per se, but it's about the rules so I think it belongs here...?

I suspect a bunch of us sort of know this intuitively, but maybe don't have the technical understanding of exactly why it's borked, and I'm hoping my little dissertation here is useful for those folks.

The Infinity rules are written in a way that makes sense if you have perfect recall and read them cover to cover. There are some oddball edge cases, issues with clarity of how things are meant to be played, and so on, but for the most part the rules work well in practice and a lot of the weird bugs are edge case interactions.

The problem is that most players, being human, don't have perfect recall, and many won't have read the book cover to cover. More likely, it's been read in chunks—probably by chapter/section—across multiple sittings.

On top of that, the game is just complex enough to require players to stop and check the wording in the rulebook regularly. Experience gradually tones this down, but if you go a long time between games (or a rule isn't used very often) even an experienced player may have to stop and check the rules text. This means that in addition to being a learning document, the rules are also a reference document.

The thing is, most of the complexity in Infinity is a result of rules interactions, not the individual rules themselves. Taken alone, most of the game's rules are simple and clear. Unfortunately, they're almost never taken alone—they interact. This tends to mean that understanding a given rule means understanding at least one other rule, which may have its own dependencies.

A good learning document presents information in an order and structure that allows the learner to parse it, digest it, and incorporate it into a mental model of the content as a coherent whole. In education this is usually referred to as a learning schema. The rulebook is okay-ish but not great at this. But it's even worse at the other aspect, being a reference document.

A good reference document has a clear structure that tells the user where to find the information they need without having to comb through the whole document. There are a few ways to accomplish this, all of which depend on first and foremost having a table of contents or index that is clear and well-organized, and an intuitive structure of information. Once you have that framework, you can use one or more of these methods for providing the actual information:

• Self-contained explanations involve putting all the pertinent information in one place; this may result in repetition, but it means that the user can find everything they need to know in one spot, either in the main text or by combining the main text with an adjacent sidebar that repeats text that appears elsewhere. This would involve, for example, including a copy of the General Movement Rules alongside every rule section involving movement. (Note that the N4 rules use this, but selectively, for states. Any rule that inflicts a state includes a copy of the rules for that state immediately afterwards in what amounts to a supplementary sidebar.)
• Page references appear in the text and refer to information somewhere else in the document, rather than repeating the information entirely. (The N4 rules use this method occasionally; one example is that certain Common Skills aren't repeated in the Common Skills rules because they appear earlier in the book, such as BS Attack.)
• Cross-references (which may include page references) or "see also" boxes tell the user that there's related information they may wish to check, and provide a link or page reference to direct the user to that information in a supplemental way. These are more or less absent from the N4 rulebook, but they are sort of included in the Infinity wiki.
• Indexing is a form of cross-reference when done properly, because it will include a given term, then multiple specific sub-terms are grouped beneath it, and all of them include one or more page number references or links. This is entirely absent from the N4 rules.
• Reminders and summaries are a compromise between a self-contained explanation and a helpful page reference, in that they may provide some information but it's a summary of more complete content that exists elsewhere. Generally, these need to include a page reference to provide context, or they risk being misleading by giving an impression of completeness, and they're often formatted in sidebars or call-out boxes to alert the user that they are supplemental to the main content flow.
• Supplemental documents are completely separate information sources that help you make sense of the primary source. In our case, that's a combination of the wiki, the FAQs, the forums, and community discussions on social media. Supplemental documents are generally inferior to a well-structured primary document, especially if the primary document doesn't direct you to them.

Note that "example" isn't on this list. Examples are useful for plain-language walkthroughs of complex ideas, but even an example can benefit from page references.

The Infinity rules don't really work well using just self-contained explanations because of the way the rules system is structured, and trying to make that method work will do more harm than good. The rules need to be presented as distributed explanations, but that makes using the other methods well even more important. Which currently isn't the case. That's a big problem, and it's compounded for new players.

tl;dr / thesis / get to the point already you wordy dork:

What I'm getting at is that the Infinity rules are not a good reference document. The Wiki sort of is, but it suffers from the inadequate cross-referencing it inherits from the written rules, and it's a supplemental document which puts it on the back foot no matter how good it is. (This is not to say that IJW is doing anything other than a stellar job. He's great. The problem's structural.)

I also think this problem can be fixed by making better use of the techniques described above, especially cross-referencing.

It may be that the community can help create good cross-referencing "see also" boxes to avoid over-burdening IJW and others. This kind of content often benefits from crowdsourcing. For one example, it's a big part of how Wikipedia does so well, because information and understanding of complex topics will tend to be thinly distributed across a lot of people.

 

The issue isn't with circular references existing, it's with the idea that the rules can give you the information you need in highly selective ways and then expect you to figure out how those things are going to interact, while simultaneously leaving out cues to find the other things that you need in order to make sense of those interactions.

Here's an easy example:

It would make sense for the rules that explain Deployment to also include a sidebar that lists all of the Skills and Equipment that may be used during Deployment, with a page reference for each thing so you can easily turn to the page for, say, Forward Deployment to make sure you understand how FD interacts with the general Deployment rules. The game designers presumably have that information handy already, and it wouldn't be difficult to add that to make the lives of players easier. That way, if they're learning the rules for the first time, they can bookmark their spot in the Deployment rules and flip forward to find the various Skills that will provide them with more options at that point in the game.

Instead, later on you find out that a given rule works during Deployment when you get around to reading that rule, either because you're reading the whole book cover-to-cover, or because you're looking at Army and need to figure out what Forward Deployment does so you can decide if that unit's any good for your list.

While it's possible that future rules will add to the list of what works during Deployment, a) that happens in other games too and people get by, and b) "living rules" should help with that.

Similarly, it wouldn't kill anyone to have a chart of Labels in the quick reference that includes what Skills and Equipment they apply to, so you could see at a glance what has the Attack or Movement label. I don't quite get why that's not a thing already. There's no place in the rulebook that just lists all the NFB things so you can know which stuff is NFB, you have to read every Skill and Equipment entry and make a list on scratch paper, or just gradually memorize them individually. That's kind of goofy, because this game has a lot of stuff to remember, and "wait, does this have NFB?" is an easy one to answer with a small chart on p. 81, and then to duplicate that chart in the Quick Reference sheets, or to have that labels chart I mentioned and then to check the NFB row to see what Skills and Equipment have it, if a NFB-specific chart is too niche.

A lot of things would be helped with a "Related Rules" box, listing applicable Skills/Equipment/States that someone might want to know about, or that might be pertinent. For the Camouflage skill, that would be something like:

• Models with this Skill may have Mimetism (Skill, p. #).
• Discover (Skill, p. #) and Sensor (Equipment, p. #) counter Camouflage.
• The Camouflaged State is a requirement for Surprise Attack (Skill, p. #).
• The Camouflaged State is a Marker State; see the general rules for Marker States on p. #.

The whole goal is to think through the thought process of someone who is looking up a rule and just needs to answer a question without having to engage in a ten-minute research project involving eight different pages in the rulebook, none of which are reached via page references in the first, second, or third rules entries the player looks at. "Where do I get the answer to this question?" is the first, unasked part of every search for information, and the Infinity rules don't do a great job of providing us with tools for that unless our questions are super obvious already, like "What does Idle do?"

(On a related note, it would sure be nice if Army had a little marker next to NFB Skills and Equipment in the printouts for a list, as that would do the job of a quick-reference chart while also saving us a step. It'd still be good to show players a list of NFB stuff the first time NFB is explained in the rules, but during actual gameplay having a reminder on the printout of the list would be more user-friendly.)

 

I hear you, but I'm not sure I am. I do think it would be quite a bit of work in aggregate—I've done the design work for rather lengthy documentation in both print and digital media, including working with authoring teams to fine-tune the information architecture and visual information hierarchy, and to build tables of contents, indices, and appendixes, as well as creating book layouts designed for print that include built-in hyperlinks that allow a user with an interactive PDF to navigate within the file and to open external URLs in their default browser.

So as a whole, yeah, that adds up to a non-trivial amount of work. Over the life of a project, it's a lot of person-hours of effort, but if it's incorporated into the production process from the get-go then it's more time-efficient than if it's done after the fact as some form of revision.

Realistically I don't expect the rulebook itself to get a major overhaul any time soon, most likely not before N5 (whenever that is). But there are a bunch of discussions on the forums that might not have happened if the rules were structured about 5-10% differently than they are; it's notable how many of the issues people bring up are about lack of clarity, rather than problems where the rules are actually broken. That looks to me like it's primarily an issue of communication and presentation, not an issue of bad ideas, which would be indicative of an area that could use additional work. I'm optimistic that we'll see fewer FAQ rulings that significantly revise the actual play mechanism in N4 than were issued in N3, but it looks like we're on track to need plenty of FAQ rulings that issue clarifications.

In the meantime, there are some straightforward quality-of-life features that would be useful additions in general, and if we're to use the Wiki as our primary reference material then I hope you'll be permitted to have supplemental content added to the entries, to make using it during play somewhat easier.

I think I can put my money (or at least, my time) where my mouth is and put some things together, along the lines of the order/skill quick reference I made for Code One earlier this year. I'll tackle the labels reference chart first, hopefully I can whip up something that gets my point across convincingly. If not, I'll eat some crow. :)

 

Fair enough. Options 2 and 4 are intended to be rather tongue-in-cheek, but they also cover reasons why someone might see the presentation of the rules status quo as desirable because of the things that can challenge players. I've heard that sort of opinion occasionally, and while I don't personally agree with it for a number of reasons, I can understand how some folks might get to that perspective. I can also see how my deadpan attempt at humor probably runs afoul of Poe's Law in this case.

A more formally correct set of options would be something like either a binary yes/no, or a yes/maybe/no, or:

• Yes, but I'm not sure how.
• Yes, and I have some thoughts on the matter.
• No, but I'm not averse to changes if they help other people.
• No, and I would prefer that no changes are made.

Looking at the current tally of results, I think that most people responding are seeing the two "joke" responses as easily ignored, but if they're off-putting I respect the choice not to participate and I'm sorry if my attempt at humor landed poorly. Given that people have already voted, I'm not sure about modifying the poll at this point....

 

OK, here's a quick reference chart that compiles all of the Labels in the game and lists what Skills, Programs, Equipment, and States have those Labels. I tried a couple of different ways to sort the lists, including pipe separators like those used in Army (Common Skills | Special Skills | Programs | Equipment | States) and I think this works the best. I've omitted instances where there are no matching uses of Labels—for example the only things with the Null Label are States—so if category is missing from a given Label it's because currently nothing in the game of that type has that Label.

Link to view the PDF on Google Drive: https://drive.google.com/file/d/1ohLhsUtrLM5hTIHxbUzIH2t96BzYvtUa/view?usp=sharing

This chart takes up a whole page, but using specific snippets in the context of other rules is a way to use it without showing the entire chart every time. For instance, where the NFB rule appears, the list of things with NFB would be helpful to have handy.

Also, the Impetuous skill lists "Impetuous Phase" as if it's a Label or Trait, but it doesn't appear in the glossary under either of those two categories. I've presumed that it's intended to be a Label and added it to this document. There are also several Labels that are in the glossary but don't appear to have been used for any rules in the current N4 rulebook. Those are mentioned in a footnote.

I haven't included the Skills from the N4 Annex PDF yet, but they wouldn't substantially change the layout of the chart.

[edit] Late addendum: I think it’s interesting how much of the Label content results from the fact that Optional is on most (but not all) Special Skills. Omitting Optional would make the chart much less imposing-looking.