What Board Games Can Teach You About Technical Writing!
Tags: documentation, technicalwriting, writethedocs, sketchthedocs
Published: 2020-08-16 02:59:23

---
title: What Board Games Can Teach You About Technical Writing!
published: true
description: A multi-part series sharing my experiences with attending #WriteTheDocs events in 2020.
tags: documentation, technicalwriting, writethedocs, sketchthedocs
series: "#WriteTheDocs - Technical Documentation Insights"
cover_image: https://dev-to-uploads.s3.amazonaws.com/i/7p2zfsc10sfitli9mg61.png
---

> The [WriteTheDocs Portand 2020](https://www.writethedocs.org/conf/portland/2020/) conference happened earlier this week. It is an amazing community-driven event for anyone who loves technical documentation. This was my first year attending, and I loved it so much I am writing a series of posts about some of my highlights attending.

> Want to watch the talks? Catch the [Day 1](https://www.youtube.com/watch?v=kGTrkCjAYgY) and [Day 2](https://www.youtube.com/watch?v=yo6uPb-WfDs) livestream archives on YouTube! And check the [schedule](https://www.writethedocs.org/conf/portland/2020/schedule/) for details.

## About #WriteTheDocs?

Want to know what the #WriteTheDocs conference is about? Start by reading my first post here. 

{% link https://dev.to/azure/i-m-attending-the-writethedocs-pdx-this-year-here-s-what-it-s-about-3f8g %}

This year the event ran for three days - with a [Writing Day](https://www.writethedocs.org/conf/portland/2020/writing-day/) on Sunday, and the regular conference (with regular sessions, [lightning talks](https://www.writethedocs.org/conf/portland/2020/lightning-talks/) and [unconference](https://www.writethedocs.org/conf/portland/2020/unconference/) options) happening on Monday and Tuesday.

## Day 1: The "Read The Rules" Talk!

After an incredible Writing Day, I headed into Day 1 with great enthusiasm. All the talks were live-streamed, making it easier for me to go back and watch segments I missed. Even before the event had started, I knew which talk I was looking forward to most - it was [this one](https://www.writethedocs.org/conf/portland/2020/speakers/#speaker-matthew-baldwin) from [Matthew Baldwin](https://twitter.com/defectiveyeti). 

And by the end of the day, I was a fan. That talk lived up to my expectations and more. Read on for what I took away from it!
{% twitter 1293175042558382085 %}

Titled `Read the Rules: What technical writers can learn from board game design`, the abstract had one sentence that caught my eye: _"a rulebook is both software and documentation, rolled into one"_. 

Till that moment I had not actually thought about the myriad sources of "documentation" that we encounter in our daily lives, from appliance manuals to utility bills and school reports. More importantly, I never made the connection between product-documentation-customer that is just as true in daily life as it is in the technology domain. 

> Once I had heard this talk, I couldn't unsee it. And now I look at every manual, and every board game rulebook with fresh eyes.

You can watch talk for yourself here (_Updated Aug 19 | 
 now with link to stand-alone talk video, replacing livestream video_)
{% youtube 7a3xEl8C3Lc %}


You can also visit Matthew's site [here](https://defectiveyeti.com/wtd/) for an incredible list of all the games he talks about. And he has his slides [posted here](https://drive.google.com/file/d/12huGOMeASwEqvhr5C-vNp8J0paDUK1Hs/view) for reference.

## My Three Takeaways

My sketchnote below provides a fairly comprehensive walkthrough of the main points Matthew made in his talk.

![Here's my Sketchnote of the talk for reference](https://dev-to-uploads.s3.amazonaws.com/i/nv55qvl716qe3r6t18no.jpg)

Here are the three main takeaways:

### 1. Self-Documenting Code: The Docs ARE The Game!

While we often think about the game (or the software) as the product, the reality is that they are just passive artifacts that are brought to life by the rulebook (or documentation). It's the docs that _provide meaning_ and make that product _usable_ to the customer. 

Once the docs ship, people start playing it according to those rules. _You have only one chance to get the core vision and mission of the product right_. Treat your docs as the most critical feature of your product and make sure you test it comprehensively (think self-testing, integration testing with team, and user testing with focus groups).

### 2. Information Architecture: Think Intent & Scanability

By [definition](https://www.usability.gov/what-and-why/information-architecture.html), information architecture focuses on _organizing, structuring and labeling content_ in a manner that _helps users find information and complete tasks_. When writing the docs, it's important to understand who the _reader_ is. And that reader is NOT you (the writer). 

Instead you need to ask:
 * (focus) what was the user looking for when they came here?
 * (intent) why where they looking for it?
 * (scanability) how easy is it for them to _find_ it?

In his talk, Matthew reviewed different styles of games, showing how diverse rulebooks tackle this challenge. _Visual cues_ (colors, images, labeling) and _consistent terminology_ (vocabulary) are key, allowing users to quickly find the _section_ of docs that provide the relevant response. 

The use of _Appendices_ helps keep cognitive overload to a minimum, allowing them to take a detour to deeper dives only if needed, without overwhelming the common reading paths.


### 3. Best Practices: Think Quickstarts, Templates & Data!

There were many examples and usage patterns around board games that were shared in this talk (and the sketchnote lists them for quick review). But the three things that stuck in my mind were as follows:

1. _Provide Quickstarts._ People learn by doing! And if you know what the main objectives of your game (product) are, then make sure you have walkthroughs, examples, checklists or other kinds of "setup" guidance that gives them a jumpstart in their journeys.

2. _Templates Transfer Learning._ Key to successful documentation is the use of consistent terminology and visual vocabulary. Users will have to _work less_ to understand docs if they see regular patterns and can make (or exploit) more connections. Creating templates for docs ensures that diverse writers end up building identifiable trails and breadcrumbs. As a writer, look for patterns and templatize them early.

3. _Take Data-Driven Decisions!_ You are not the reader. And despite our best efforts, we will always find [desire paths](https://en.wikipedia.org/wiki/Desire_path) where users who find existing paths unsatisfactory, simply create their own shortcuts to optimize their journey or fulfill their intent. To understand this, it is critical to _instrument_ your documentation system, _capture and analyze_ the usage data, and _iterate_ your information architecture so that you can ["pave the cowpaths"](https://en.wiktionary.org/wiki/pave_the_cowpath) faster.


## Discussion

There were two things that this talk did for me. 

First, it made me pay closer attention to all printed documentation that I encounter in every day life, and ask _why did they add this_ (for every section or feature), followed by _what could I do to make this better?_ (specifically looking at gaps in my personal use of that artifact. And that exercise has been helpful in improving my own thinking around writing.

Second, it made me want to do more research into more inclusive information architectures. The [WriteTheDocs Style Guide](https://www.writethedocs.org/guide/writing/style-guides/) section has a lot of guidance here. In some sense, this has to do with broadening our testing practices to make sure we are including a more diverse set of users in our assesment - so we are not just asking _what is the user's intent_ but starting by first asking _who is our user?_ and making sure we have representation across genders, abilities, languages, ages and cultures.

If you had other insights or comments, do share. And next time you open a board game to play, take a minute and read those rules with fresh eyes.