Documentation, Scaffolding, and Paper Mario

Introduction

A few weeks ago, I started playing Paper Mario: The Origami King. It's the latest game in the Paper Mario franchise, available on the Nintendo Switch.

As I worked my way through the first few battles, I was impressed by the way the game introduced the new battle system. It reminded me a lot of the best practices I keep in mind when writing documentation (or really any educational content). I wrote about some of these parallels on Twitter.

Video game tutorials and documentation both have a similar goal: to help users build up the knowledge and skills they need to be able to play successfully on their own. If the tutorial is done poorly, new players will feel overwhelmed and give up before they make it to the really good part of the game. But if done well, players will slowly get better at the core skills of the game without even consciously realizing that it's happening.

In this article, I outline three lessons from Paper Mario: The Origami King that you can use to improve your documentation and set your users up for success.

But First, Some Context: The Paper Mario Battle System

In case you haven't played Paper Mario, here's a quick video trailer to show how battles work. (The part about the battle system starts at 2:14.)

In each battle, a group of four or more enemies appear on a circular grid of rings. As Mario, you can attack enemies by jumping on them or hitting them with your hammer, consistent with the previous Paper Mario games. But in The Origami King, there's also a new twist (literally): you can rotate and slide the rings on the map to line up the enemies. If you get them all perfectly aligned, your attacks for that round deal extra damage. (There's some other stuff too, but we'll get to that in a bit.)

If the video makes it look complicated, that's because it is. Especially when there are multiple sets of enemies and it's not obvious how they're supposed to be lined up.

But the great thing about this game (and many video games with complicated mechanics) is that the tutorial doesn't just throw you right into the deep end and expect you to figure out how everything works. It starts you off with easy puzzles and gradually increases the difficulty level as you become more skilled at solving them.

It scaffolds your experience through the game.

What is Scaffolding?

In education, the term scaffolding refers to breaking down a complex concept into a sequence of smaller chunks. As learners progress through the sequence, the newer lessons build on the concepts that came before, which helps students deepen their understanding.

To quote The Glossary of Education Reform:

The term [scaffolding] itself offers the relevant descriptive metaphor: teachers provide successive levels of temporary support that help students reach higher levels of comprehension and skill acquisition that they would not be able to achieve without assistance. Like physical scaffolding, the supportive strategies are incrementally removed when they are no longer needed, and the teacher gradually shifts more responsibility over the learning process to the student.

In other words, scaffolding makes problems slightly easier for students at first, to give them time to build the fundamental skills they'll need to be able to solve harder problems later on.

For a more concrete example, think back to when you first learned how to write an essay in school.

Your second-grade English teacher (hopefully) didn't just give you an open-ended prompt and set you free to write the entire paper on your own. They probably taught you how to write a single paragraph first. Maybe they made you fill in an outline template to help yourself stay on topic. Maybe they gave you a reference sheet of topic sentence starters or transition phrases to help your ideas flow more smoothly. The specifics aren't important. The point is that they gave you extra support when you were getting started, to help break down the big challenge of writing a paper into smaller, more manageable chunks of work.

Sure, by the time you got to high school or college your instructors weren't giving you quite so much guidance. But at that point, you didn't need it. You'd already mastered the fundamentals of how to write an essay, which meant your instructors could spend more time focusing on more advanced topics.

Scaffolding in Paper Mario: The Origami King

In the rest of this article, I'm going to highlight three parts of The Origami King that help scaffold the player's experience. Each one corresponds to a key lesson that can be applied to writing documentation:

• The tutorial: Focus on one new idea at a time.
• Boss battles: Only introduce a concept when you need it.
• The Battle Lab: Provide opportunities for practice.

The Tutorial: One New Idea at a Time

Like many video games, the first part of Paper Mario: The Origami King is a tutorial. Mario's new sidekick, Olivia, takes the role of your teacher, cheerfully making suggestions to guide you through the first part of the game.

The tutorial writers behind Olivia clearly understood the concept of scaffolding. Olivia introduces each of the battle system mechanics gradually over the first several battles:

• In the first encounter, Olivia basically directs your every move. She teaches you the controls to rotate the rings to line up enemies for a jump attack. The puzzle is simplified so that you only have to rotate one ring, and circles appear on the grid to show you exactly where the enemies should end up. In the second wave of enemies, Olivia teaches you how to line up enemies for a hammer attack.
• The second encounter has the exact same arrangement of enemies, which provides you an opportunity to practice the skills Olivia already taught you. This time, Olivia gently reminds you what you need to do (line up the enemies, and use the right attack for the arrangement), but she doesn't tell you explicitly how to do it. She also teaches you a new mechanic: you can time your attacks to do even more bonus damage to enemies. At the end of the battle, Olivia also tells you that you can block enemy attacks.
• In the third encounter, the ring puzzle is slightly harder, requiring two rotation moves instead of just one.
• In the fourth encounter, Olivia teaches you how to attack multiple times in the same turn.
• The next few encounters don't introduce any new mechanics, but they let you practice what you've learned so far.
• Once you reach the next area, Olivia teaches you how to slide sections of the rings, as well as how to switch between sliding and rotating rings.

By gradually introducing one new mechanic at a time, the tutorial writers give players a chance to practice getting good at each skill before moving on to the next concept. (More on practice in a bit!)

Does this mean that players' first few battles are sub-optimal? Sure. But they're just getting started, so it's okay. Eventually, players will have access to the full suite of battle mechanics and be ready to kick some origami butt. And more importantly, because they're only learning one new thing at a time, they won't feel overwhelmed and quit partway in.

How to Apply This to Your Documentation

• Break up complicated topics into smaller chunks. If you find yourself trying to explain a bunch of concepts all at once, try to tease them apart into a series of shorter docs (or even just separate sections of the same doc).
• Be intentional about the order in which you introduce new ideas. Each step in the sequence should help readers build or accomplish something. (Players can still win a battle even if all they have is jump and hammer attacks!)

Boss Battles: Only Introduce It When You Need It

Boss battles have an entirely different game mechanic from regular enemy battles. (The game trailer showcases boss battles at 3:48.) Instead of trying to line up enemies, you rotate and slide the rings to create a path to get Mario in front of the boss in the center of the arena.

But you don't find out about those mechanics until you reach the first boss. The game developers protect you from that extra complexity until you absolutely need it.

Imagine if Olivia explained the boss battle mechanics in the first encounter of the game. What would that even look like? "Hey, jump on these Goombas. Oh and also, some day you'll reach a giant enemy and you'll have to do something totally different to fight them." It wouldn't make any sense. Since the information wouldn't be relevant yet, players would probably just skim past it and forget about it by the time they needed it in an actual boss battle.

It's fine to tease the "advanced" boss battle mechanic in the trailer, to hook people's attention or give them a sneak peek of what's to come. But in the actual game, the developers don't explain all the nitty-gritty details until they're sure players have a solid grasp of the basics first.

How to Apply This to Your Documentation

• Keep your Expert Blind Spot in check. It's hard to learn new things. Humans can only keep roughly four pieces of information in their brain's working memory at the same time, but learning a new technology frequently requires juggling many more than four concepts. As the documentation writer, it's your responsibility to protect your readers from unnecessary mental load as they get up to speed with your docs. That means putting yourself back into the shoes of a complete beginner. What implicit information do you know as a writer that your readers might not know yet? Where can you add those details so that they are easily discoverable?
• Separate the main idea from the edge cases. I've noticed that sometimes docs jump deep into the weeds of implementation before establishing a big picture for readers. But comprehensiveness comes at the expense of clarity. Is it obvious to a newcomer that those edge cases are an "advanced" feature? Or is going into detail just muddying up their understanding of the basic idea? Yes, it's important to tell folks about edge cases somewhere. But your readers need to have a clear understanding of the main idea first. Try using headers and labels to clearly mark advanced topics that can be skipped by beginners. Better yet, pull edge cases out into their own "Troubleshooting" doc, and add a callout at the top to highlight prerequisite knowledge for beginners: "Looking for an introduction to X? Here's a link to the overview doc!" (Think of it like a side quest.)

The Battle Lab: Provide Opportunities for Practice

One of the hidden gems of The Origami King is the Battle Lab. It's a special building you gain access to early on in the game. Inside, there are special machines that let you run practice drills for individual battle mechanics. You can practice timing your attacks, solving ring puzzles, and even rerunning previous boss battles! And, because it's all just practice, you don't get a "Game Over" screen if you die in one of the battles.

I love the Battle Lab because it's a perfect example of scaffolding. Advanced users who already feel comfortable with the battle mechanics probably won't spend much time there. But beginners (or people who just can't seem to figure out the ring puzzles, like myself) can spend as much time as they want in a low-risk environment, gradually improving the skills they need to be successful in the game.

How to Apply This to Your Documentation

• Add checks for understanding to help readers test themselves. Consider adding a few short prompts to the end of each doc. These could be open-ended questions ("Why is it important to do X?"), or they could be sample exercises that require the reader to put some content into practice ("How would you write an API call to accomplish Y?"). The checks should be tied to the main idea you want readers to take away from that doc. By testing themselves on what they just read, readers can check if they understood the material or if they need to go back and reread something.
  • Checks for understanding are a good place to collect metrics! Track readers' answers to each question. If lots of folks get a particular question wrong, you might need to investigate where they're getting stuck and make improvements to your doc.
• Provide a sandbox where readers can practice applying new ideas. Consider creating a sandbox mode or an example project that users can explore to practice a new topic. You could either give them some starter code with a prompt for new features to add, or you could give them a completed code example showing how the final product works. (Or both!) In either case, be sure to provide text prompts to guide their exploration and highlight the important bits.

Conclusion

Figuring out how to teach a whole new technology from scratch can be a daunting task. But as documentation writers, we don't have to recreate the wheel every time! We can learn from other educators, including video game tutorial writers.

To summarize the lessons from this article:

• Focus on introducing one new idea at a time.
• Only introduce a concept when you need it.
• Provide low-risk opportunities for practice.

If you're interested in hearing more of my thoughts on education and the tech industry, follow me on Twitter! I'd love to hear your thoughts on this post (or on documentation in general).

Are there any other parallels you've noticed between video game tutorials and programming tutorials? What other video games do a good job of getting new players up to speed?

Additional Resources

• Working Memory: Video. (Learning How to Learn for Youth; Coursera course by Arizona State University)
• How to make a good video game tutorial: Article with corresponding video. (School of Game Design)
• Practice Perfect: 42 Rules for Getting Better at Getting Better: Book. (Doug Lemov, Erica Woolway, and Katie Yezzie)