What tech docs can learn from video game tutorials?

Your job is to write the documentation, including some get started guides and tutorials, for your company's or project's software. The software is beautiful and it can do quite a few things – and as is often common for software or libraries can be configured in many ways.

You jump on the documentation, going through from the start towards more complex features and explaining and referring to the reference documentation as you go on, providing the user all the knowledge they need to make their own decisions.

But is that the best approach?

At the end of last year, I was brainstorming and researching ideas for how we could improve our tutorials and guides for Firefox's browser extension documentation website. My journey there ended before I managed to craft those ideas into a reality but one path I ended up following was to look into what video games are doing with their tutorials.

Only show what's necessary and build up from there

In Mark Brown's wonderful video essay GMTK: Can we improve tutorials for complex games, Mark mentions Bruce Shelley's idea of inverted pyramid of decision making that Bruce talks a bit about in Soundbit podcast episode from January 2020:

Bruce Shelley: I had a phrase, I guess, when I worked at Microprose Sid  said it was my phrase. It's called the inverted pyramid of decision  making. So the idea is that you start the game with one unit and you  make a decision with it and then that opens up a door.‌‌‌‌Now you  can make two decisions. Or you build a second unit. Now you have two  units to use. And then you have four and you have eight and you have 16.  And these decisions like ramp up, so it starts off as a tiny bunch of  decisions and it quickly grows, balloons. And I think that does a great  job of getting people engaged. And we had this idea that you had 15  minutes to engage somebody or you'd lose them.

There are a couple of thoughts in that which really resonate with me. One is that we don't have to start with all the complexity of our software or library. Sure, let's provide the developer a link to resources if they want to dive directly to the deep end right away but for those who are exploring, let's start with small and add a few things at a time.

Another thought is the last sentence in the previous quote: "And we had this idea that you had 15  minutes to engage somebody or you'd lose them." This is often the case in technology as well. If someone's taking a look at your project, you need to catch their attention, start small and guide them towards more advanced topics bit by bit, providing a small pieces of feeling of success at each point.

It can be very discouraging to follow a tutorial or read documentation for a few hours only to realize that what you attempted to build didn't work for some reason or if it did, maybe didn't solve the actual problem you had.

Building your tutorials in a way that take a small step at the time, provide a success point after each step. This is not only great for dopamine hits and engagement but also for making sure that the feedback loop remains tight.

Goal-driven rather than feature-driven

Often in video games, the tutorials are shown to the player one at a time, when the time is right. Each time, they help you achieve your immediate goal by providing you the exact tool to do that. When you start a new game and you're taught how to jump, a great tutorial doesn't teach you all the dozen ways you can jump at once but rather teaches you exactly the one jump you need at that point.

After that, you can experiment with yourself with different jumps (or by analogy, ways to run the software) and explore to find new exciting things or you can follow the tutorial to continue on the set path.

By being goal-oriented, the tutorials help the player avoid being overwhelmed and confused. Instead of telling the player "here are all the things you can do in the game, good luck figuring out what you actually need to do here", the game guides the player to solving an actual problem with the smallest subset of tools needed.

In tech, a feature-driven documentation focuses on all the individual features or capabilities of a system: maybe it's the modules or functions or commands in your software and it aims to build your understanding of the usage in a holistic way and leaves the application of that understanding as a homework for you.

Scott Sehlhorst has a great blog post about Goal-Driven Documentation that has a similar approach to the video game tutorials. Instead of focusing on what the implementation of the software is like or what the user interface is like, it focuses on individual use cases that achieve a distinct goal that the developer has.

Scott Sehlhorst: We write documentation so that people can more easily do the job, not so that they can use the tool.

Each use case focuses on only the things that matter to it and even more importantly in my opinion, provides the right options (or at least smart defaults) for the specific mission.

One documentation that I enjoy a ton that does a marvelous job with this is tldr pages. It's a command line tool that gives you a list of community curated use cases and commands to achieve them:

➜ tldr zip

zip

Package and compress (archive) files into zip file.
See also: `unzip`.
More information: <https://manned.org/zip>.

- Add files/directories to a specific archive ([r]ecursively):
    zip -r path/to/compressed.zip path/to/file_or_directory1 path/to/file_or_directory2 ...

- Remove files/directories from a specific archive ([d]elete):
    zip -d path/to/compressed.zip path/to/file_or_directory1 path/to/file_or_directory2 ...

- Archive files/directories e[x]cluding specified ones:
    zip -r path/to/compressed.zip path/to/file_or_directory1 path/to/file_or_directory2 ... -x path/to/excluded_files_or_directories

In the snippet above, tldr pages offers me few practical and specific ways to use zip command. It doesn't abstract them away nor offer multiple options for each but it's a mapping of one use case to one command.

Allow the community to participate

As long as there has been video games, there has been guide books and walkthroughs and these days, a lot of games have community written wikis that help players find information, solve problems and learn new things.

It has grown even further with the emergence of Youtube: for the popular games, you can find video solution to almost any problem you face in the game. And quite a lot of videos showing things you didn't even know you wanted to do in the game.

These being done by the players is great because a player approaches the problem from a very different viewpoint than the developer of the game because they discovered the solution without knowing it before hand.

For a tech team, the imagination and the resources of the developer team are always limited and it's impossible for one person or one team to come up with all the possible examples and use cases in your tutorials.

A great way to expand your technical documentation from these guided and narrow tutorials is to open up the reference documentation for your developer community.

Developer communities are great for that as well since developers tend to like to share and help each other. A great example of that is PHP's reference documentation. On each page (like for example, this rsort page) has the official documentation and below that, User Contributed Notes section where community members can offer more snippets, discuss and help other people to learn more and learn specific usages that grow the value and usefulness of the documentation.

Related writing

• What tech writers can learn from video game manuals by Fabrizio Ferri Benedetti.