The WriteTheDocs Portand 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 and Day 2 livestream archives on YouTube! And check the schedule for details.

About #WriteTheDocs?

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

I'm attending the #WriteTheDocs PDX this year. Here's what it's about.

Nitya Narasimhan, Ph.D for Microsoft Azure ・ Aug 10 '20

#opensource #documentation #virtualevents #a11y

This year the event ran for three days - with a Writing Day on Sunday, and the regular conference (with regular sessions, lightning talks and 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 from Matthew Baldwin.

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!

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)

You can also visit Matthew's site here for an incredible list of all the games he talks about. And he has his slides posted here for reference.

My Three Takeaways

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

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, 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 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" 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 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.