Designing Design Documentation

Overview

This page contains tips, advice, and best practice for writing technical design documentation. Good documentation is specific, easy to read, and easy to use.

Background

A human's ability to complete tasks is limited by their working memory. The amount of working memory required to complete a task is called cognitive load. A portion of cognitive load is imposed by the structure of the task, called the extraneous load. The other portion is the load intrinsic to the task, which represents the inherent complexity.

The reader of our documentation is performing the task of learning. As documentation writers we can only control how the information is structured, and thus the extraneous load of the learning task.

The more difficult documentation is to understand and use, the higher the cognitive load, and the harder the user will need to think to effectively use the documentation. When attempting to do difficult technical tasks with high intrinsic load, difficult to read documentation can make the problem worse. The advice here seeks to minimize the cognitive load of written documentation through the reduction in extraneous load.

Basics

Purpose of Documentation

Documentation exists to communicate knowledge you have to someone else without having to tell them. To that end, it could be a design, a process, what happened at a meeting, or anything else you need to teach. If writing documentation seems boring, just remember the better you write your page, the less people will bother you with questions.

Audience

All documentation has an audience with needs and context. Consider who your page is for, and what they need from the documentation. Think about what knowledge they have, and what knowledge they need to use the page (If there's a gap here, provide links to resources to fill these gaps). Also consider the context someone will be using the page. Will it be to learn a skill? As a reference page? As documentation for a new feature they must implement? Each situation should change the way you structure and present your information. 

When you define your audience and context, consider if a better solution already exists! Epic Games already has documentation for developers who need to learn event dispatching so only write a page on that topic if it adds something new or studio specific.

Language

Use simple, precise language with authority. If someone is reading your documentation it's because you're the expert. Don't give them pause to second guess your advice. If there are multiple ways to do a process, present them and list the tradeoffs. 

Using Structure

Structure allows you to segment information into more digestible pieces by leveraging the reader's past experiences.

Headings

Headings contextualize the information contained within them. By leveraging headings, you can impart more information than words alone. For example this information is about quality documentation; more specifically the structure of documentation, and even more specifically the effective use of headings.

Page Hierarchy

This is the page's position within the larger wiki. Information that’s required to understand the page should always be either on the page itself or at a higher level than the page it’s on. Never put required info deeper than where it’s required. In effect you want users to read as few pages as possible, and give them the knowledge necessary to dig deeper if needed. The higher up a page is, the more broadly applicable it should be to the users.

If a page starts to have 2 different audiences, consider splitting it into two different pages so each can be better tailored to a group. If there’s a group that’s a subset of another group, address their needs in a deeper page, and leave the common knowledge in the page under question.

Audience Funnel

Another way to think of page hierarchy is through audience funnels. As you drill deeper into a page hierarchy, the audience for each page becomes progressively more specific. For example:

All Employees-> Employees using Unreal-> Employees using Unreal Plugins-> Employees using a specific Unreal plugin-> Employees setting up the Unreal plugin in a project-> Employees extending the Unreal plugin

All Employees-> Employees using Unreal-> Employees using Unreal Plugins-> Employees using a specific Unreal plugin-> Employees designing the Unreal plugin -> Employees designing UI for Unreal plugin

Introductions

Page introductions can contain one or more of: Background, Overview, and Goals. Different pages have different needs and you'll have to make a judgement call about what sections to include. Keep in mind that the more content you add, the less likely it is to be read in its entirety.

Background

A background section communicates foundational information the page is built upon. Quality background sections provide context for the page. This also allows you to provide links to related resources, list assumptions about the knowledge level of the reader, or tell the reader to read other information first. Your page may not need a background section if there is minimal foundational information or if the background is already known by the entirety of the audience.

Overview

The overview section is a short description of the information contained in the page. A good overview section enables readers to quickly evaluate the page’s value. 

Goals

The goal section tells the reader what they should take away from the page. Goal sections are extremely important for pages that will be built upon by other authors in the future since it allows them to change outdated information and add new information to more effectively complete the stated goal.

Structures

Links

Links are used to add related information to your page. You may want to link to required reading at the start of your page, or additional reading to learn more at the end.

Regardless of placement all hyperlinks should have display text that replaces the link.

compare:

Google: https://www.google.com/

google

Lists

Lists can be numbered or bulleted. Numbered lists are used when the order of the list items is important. Bulleted lists are  used when the order is irrelevant.

All numbered lists have an order, whether that be importance, date added, order of operations, or priority. If there is no apparent order, the reader will assume one. To avoid giving the wrong impression, make a choice based on the most important quality. For example: processes are always in the order of operation.

Tables

Use a table if you need to display one or more characteristics of a list of items. Use column titles to let the reader know what the data is in the column. Make sure to order items based on their most important characteristic (name, order of operation, date, type, etc.). Even if items are primarily ordered by type, date, or some other parameter, they should be secondarily ordered alphabetically.

If you are adding an item to an already existing table, make sure to follow the currently existing ordering logic. Do not just add the item to the bottom.

Conclusions

Conclusions wrap up the information contained inside the page, and let the reader know what takeaways they should have made. This section is rarely needed in technical documentation, but if it helps your audience achieve their goals on the page, it’s great to include.

Don’t “Save” Your Ideas

                As a new game designer there’s a problem I wish I had known about when I was first trying to start. I have a ton of awesome ideas, but I have no idea how to implement them. These ideas were so good that I didn’t want to waste them on the version of me that was just starting. There’s no way I could make them the way I imagine them in my head right now! So instead, I would “save” them for later, and try to come up with a disposable idea to learn on. Of course, I could never find a disposable idea that I was passionate enough about to finish. If you’ve ever experienced this then I’d like to pass along some advice I wish I had.

                Working on an idea you love is hard, let alone one you don’t like. If you’re ever going to get any good at game design then you’ll have to design games. And to see if your designs are any good you’ll have to actually finish making those games. This means you’ll have to use ideas that make you excited and figure out how to make them as best you can. If you can’t make an idea you’re excited about happen then good luck working on other people’s ideas.

                But don’t despair at using up your good ideas! As you progress in your skills as a designer, you’ll find something magical happens. You realize that your old ideas are actually not all that great and more importantly you’ll find out why they aren’t great. Furthermore, you’ll be able to come up with even better ideas and iterations of your old thoughts.

                 If you strike gold and realize that one of your earlier ideas was actually the best one don’t despair! You can always come back to it and keep improving it. Even the biggest studios in the world resort to making sequels of their best ideas and IP. If they can reuse them then you can do the same.

                So get out there, take your favorite idea out of the vault and try to make it happen!

Minimum Viable Campaign: A Guide to Setting up Your D&D Campaign in Half an Hour

                If you’ve always wanted to be a Dungeon Master but have had a hard time setting up campaign, or you’ve got a game starting soon you haven’t prepped for this guide is for you. In this post, I’ll show you the bare minimum you need to set up a D&D campaign, and some suggestions on where to add some more time if you have it. The areas you’ll need to set up are The World and Tone, The First Adventure, and I’ll give some productivity tips too. The effective use of this post assumes access to the 5th edition Dungeon Master’s Guide (DMG) and Monster Manual (MM).

The World

                To set up your world you just need a style and a starting area. The style needs to be decided first because it informs every other decision you should make about your world. Swashbuckling adventures need interesting islands and port towns to explore, while sword and sorcery settings need evil sorcerer kings and blighted landscapes. Some example styles are Epic Fantasy, Sword and Sorcery, Mythic Fantasy, Horror Fantasy, and Mystery. For more examples check out pages 37-41 of the DMG. But don’t take too long, just choose the setting you think is coolest.

                Once you decide a style, you need the setting. This starting area consists of the region name, the starting city, and what the environment is like. Adding a map is great, but it takes time and requires you to build the whole world ahead of time. It’s best to build in chunks, describing only the area immediately around the players and keeping the rest of the world mysterious. For your first session, all the players need to know is where they are right now, what that area is like, and what is close by. This is also your chance to establish your style. Is it the sprawling capital city of a great kingdom, an outpost on the edge of untamed wild jungles, a monetary complex in the midst of a blighted hellscape, or an elven city carved into a magical forest? All of these settings set up different types of adventures for your players and set certain expectations about how the world should feel.

                If you have extra time, creating a regional map can be a great way to communicate the locations in your world. Creating the history of your world and making a timeline of important events is a good way to further establish your style

The Quest

                The first quest the players embark on is their first introduction to your world. Every quest needs the following: Characters, an Objective, and a Place. The standard arrangement is to have a questgiver give the players a goal, the goal take the players to a dungeon, and have a villain oppose the goal. Other arrangements of these certainly exist so let’s break down the components.

Characters

                Every Non-Player Character (NPC) in your world needs at a bare minimum a name, traits, goals, and resources with which to achieve those goals. Names are easy, use the last name to establish familial relationships with other characters and a first name that you think fits. For traits, just choose four concepts that describe a character, and make two seemingly contradictory if you want an interesting character. A character who is Humble, Hard Working, Loving, and Proud can cause some interesting tensions between her humility towards her work and her pride towards her family. Next, you need some goals for the character. To make a character more important give them many short and long term goals. For average characters, one general goal is sufficient. A blacksmith might want to earn enough money to send his only child to the national academy. The powerful wizard main villain of the campaign might want to secure a suitable phylactery to harbor her soul in the short term, establish a network of spies across the land, gain favor with an ancient dragon, and establish a marriage alliance with a Barbarian prince, all in an effort to start a yearlong ritual to become an immortal lich. Having a few supporting goals to the main goal will give the players opportunities to interact with the main villain and thwart her plans without killing her off right away. Lastly a character needs some resources with which to achieve their goal. These can be monetary, relationships with people in positions of power, influence, or property. Simple characters like a blacksmith might only have their shop, and their friend on the town watch. Kings will have armies, diplomatic networks, alliances, vast gold reserves, a fortification, food distribution networks, roads, and industries at their disposal. The resources at their disposal measure the power of a character.

Objectives

                Objectives are just the goal of the quest. Don’t be afraid to just steal the plot of one of your favorite movies, books, or games and change it slightly. Goals can have many layers if you want them complex, or be straightforward if you want a focused experience. This is where the character goals become interesting. Allies become those who have goals aligned with the quest, and villains have opposed goals. Allies use their resources to help the players achieve their goals and villains use them to stop the players.  This is also an opportunity to reinforce your world’s style.

The Place

                Many D&D adventures take place in dungeons, but feel free to come up with any other locations that make sense for your quest. Dungeons are easy because you can control the experience of going through the network and you confine the players to a known space. The place should have a description and opponents who live there. These inhabitants are the enemies the players will have to defeat to accomplish their goal. The description is what the place looks and feel like. With more time you can create a map of the place, but when pressed for time you can just make a sketch on a sheet of grid paper when necessary. Don’t be afraid to just make something up on the spot! Additionally you can plan out encounters based on page 82 of the DMG with extra time, or just choose some monsters from the monster manual that make sense and have a challenge rating lower than the players level. As a rule of thumb players can face up to one monster that’s equal to their challenge rating (CR), two monsters of a 1 lower than their level, and 4 monsters of CR 2 lower than their level. Feel free to add a few random treasure hordes to the place too (DMG pg 136-139). Players love treasure, and better yet players love rolling dice to decide the treasure. Just record which tables you’ll roll on and where in the place they are.

The Quest Continued

                Once you have an objective, some characters with goals that intersect with the goal of the adventure, and a place for the adventure you’re good to go! Whenever you face a question during gameplay, just do what feels cool and right without worrying how exactly it fits into the world. After the night is over you’ll have time until the next session to figure out the ramifications in your world.

A Twilight Imperium Discussion

                The other weekend I played the third edition of Twilight Imperium (TI3) for the first time and was blown away. This board game sees each player take control of an intergalactic civilization vying to become the galaxy’s next leader. The game plays like a wargame, but adds elements of technological advancement, diplomacy, and objective cards to determine the winner. It took us about 8 hours to play, and in this blog post, I’ll highlight some of the best parts of the experience and some potential improvements.

                First off let’s take a look at this game’s table presence:

                This game is huge, and component is packed with details. In the lower left hand corner you see my reserve of black units, my technologies, currently occupied planets, diplomats, and current trade agreements. Then each player has a reference sheet with tokens showing their allocation of commands, the galaxy itself, action cards, the current public objectives, the currently enacted laws, the strategy card each player is taking this turn, and it just keeps going. The game took 8 hours in part because there’s just so much information to take in and consider. But the overwhelming number of components is also enthralling. Just look at my giant fleet of ships in the lower right of the board! Doesn’t it just make you want to take over the galaxy? And the number of options available to you makes you feel in control of a sprawling race of people.

Player Story

                If good board games are story machines TI3 created one of the most immediately compelling stories I’ve ever experienced. My faction was called The Nekro Virus. I can’t vote on laws at the galactic council, and I can’t research technologies like everyone else. Instead, I can only gain technology by defeating an opposing unit and copying a technology of that opponent. On my first turn I chose the diplomacy action and was allowed to propose a new law to the galaxy. The law I chose immediately gave everyone the WAR SUN technology, allowing them to build death star like weapons. The diplomat from the goblin race assassinated my diplomat, but everyone went along with the proposal and got the tech. Unfortunately I didn’t realize that since I was the virus I couldn’t earn new technologies this was! So, I had to defeat someone in battle first. Later on in the game another player encroached on my territory, so I quickly retaliated and captured their home world. However, by the end of the game everyone was so exhausted and the game started to drag that a few players colluded to end it unceremoniously. The game started off so strong that I loved it just from a few moves, but ended so abruptly and poorly that I felt robbed of the epic conclusion I thought I deserved

Victory Point Win Conditions

                To win in a game of TI3 you need to get to 10 victory points. These points can be gained by completing a random secret objective, and by completing public objectives. These public objectives for our game were “pay 10 resources to gain a point”, “capture at least 3 unoccupied planets this turn”, and “control at least 5 planets”. These sorts of objectives don’t lend themselves to epic conclusions. Every battle, technology, action card, and political meeting is so rich with theme that having these generic objectives feels wrong. And equally disappointing is when someone just happens to meet the criteria for their secret objective. It’s extremely difficult to intentionally stop a player from completing these conditions, especially if they’re on the opposite side of the galaxy. Victory point win conditions are often included to more easily allow for a variety of strategies to contribute to victory, like diplomacy, warfare, and trade. But the objectives I experienced mostly just boiled down to controlling a lot of territory and making good use of your resources.

Structural Win Conditions

                More appropriate for wargames are structural victory conditions. Risk is a great example of a structural victory condition; a game about global domination that you win by dominating the whole board. A game like Twilight Imperium could benefit from giving players huge structural advantages from completing objectives in the game instead of points. Maybe taking over 5 planets gives you a huge boost in production, capturing 3 unoccupied territories allows an extra production phase, or spending 10 victory points lets you gain an extra technology. This would also allow players to feel a stronger sense of progression, by gaining immense power over the game. To win the victory could be the last player to have a leader figure alive, the player to capture all the homeworlds, or the player to hold the center planet Mekatol Rex for a number of rounds.

TRPG Combat System Design 101: Variables

                Tabletop RPG combat is a sore spot for many players. Even the most popular system: Dungeons and Dragons can get dull unless you’re a wizard or the dungeon master is exceptionally skilled. In this RPG combat design series, I will be talking about how to design the turn-by-turn combat. This post is about all the variables you can use to add depth to your system.  

                An action is the singe non-movement activity a character does on a player’s turn. This is mostly attacking an enemy, casting a spell, or defending oneself. Let’s take a look at all the variables you can tweak for any given actions.

1.       The Speed of the action in terms of when it resolves in initiative order. Many games represent this by having players roll initiative at the start of combat to determine the order of actions. This makes initiative quick to determine, but detaches it from the actions a player is taking on their turn. Outbreak has players roll speed dice based on each action, so the players must decide between acting quickly and acting more powerfully. This works great in a horror setting, since a player may find out their action is no longer useful when they finally act! However, this requires a round of action declaration where every player says what they are doing and which action they are taking along with a round of action resolution that changes each round. This greatly increases the time it takes to run combat.

2.       The Accuracy of the action in terms of how reliable it is. Virtually every game uses accuracy to some extent. This can be the odds to hit a specific enemy based on a character’s stats, or the odds that a spell or action will be successful in absolute terms (This spell has a 50% of working regardless of enemy). If an action directly affects an opposing character, it’s a good idea to vary the accuracy so there’s a difference between powerful and weak opponents. If the action supports an ally then it’s a good idea to make it automatically successful, so players don’t feel punished for helping each other. Fixed random chance is good for item use, or spell effects mainly cast into the environment (wall spells, controlling the weather, summoning monsters, etc.)

3.       The Potency of the action in terms of how effective it is. The typical representation of this variable is the damage dealt by an attack based on the weapon used. This can be the magnitude of effect of any attempted action though. The amount of healing done by a spell, the distance an enemy is pushed by a charging action, how strong the summoned magical armor is, how far you can detect magic, how hard it is to dispel a magical effect, and anything else you might try!

4.       The cost of the action in terms of how many resources are used to attempt it. Dungeons and Dragons used to use a resource management system only for spellcasting. Casters got a number of spells per day and must use them wisely or they will have to wait until the next day. Now many other classes get actions that can be used only once per encounter, per rest, or per day. Many other RPG systems use a fatigue system where players can gain fatigue to improve the accuracy or potency of an action. Think about using cost to balance weapons of different potency or special attacks that otherwise would always be used (in D&D that could be the fireball spell, the highest damage weapons, the power attack feat, etc.). Giving players a resource to manage makes combat instantly more engaging as players will need to make choices about when and where to use those resources. Cost can also be measured in how many turns it takes before the action occurs although this should be avoided for actions designed to happen in combat. Having to wait 3 turns for an epic killing curse might make sense based on its Potency, but it’s no fun to do nothing for 2 rounds of play.

5.       The range of the action in terms of how far it can affect. Swords can only be used up close, but laser sniper rifles might be able to shoot across a city. Use range to give variety between the actions characters can take with weapons or the spells they can cast. What does a healing action that requires a player to be next to a character look like compared to one that can be shot from a gun? Closely related to range is line of sight, which is where within range the action can affect. Typically, a character can’t use an action on someone hiding in a building or who is otherwise unseen. However, having an action that can attack around corners, shoot in the dark, or cast spells behind a building adds depth.

6.       The breadth of the action in terms of how many targets can be affected. Can a character only attack one opponent with a sword, or can they hit many enemies with a blast of confusion. Think about how many targets an action can affect and whether it should have an area of effect. Spells make a lot of sense to have AOE to represent large magical powers, but don’t be afraid of having weapon attacks affect many enemies if you want a fantast feeling. Closely related to breadth is the rate of fire or rate of attack. How many individual attacks a character gets when they attack multiplies the potency of the attack and gives a faster and more skilled feeling to the character. What if a character has to choose between one single high powered attack and attacking several times with a less potent smaller weapon?

7.       The versatility of the action in terms of how many situations it’s useful in. If your game features underwater storylines, that greatly changes the value of fire and electricity spells. Think about adding highly effective, but situational actions to a player’s available choices along with less effective and more generally useful actions. Also give players the ability to create the circumstances that make their situational actions more effective. A lightning sword that grows more powerful during thunderstorms becomes much more interesting if a player can summon a dangerous storm during battle. Giving players actions that let them change the environment are a great way to add versatility. A spell that creates a cube of wood can be useful as a bridge, a wall, repairing a house, stopping a flood, or anything else the player can imagine. Versatile actions are great for giving players options, but restricted ones can be good too. Just make sure the restrictions aren’t too constricting, are interesting, and can be avoided or worked around. A bow that can only shoot orcs is much less interesting than a bow that is especially potent against orcs.

8.       The Duration of the action in terms of how long its effects last. When considering the duration of an actions’ effects, consider both the impact on the current combat, and the effect after the combat. A spell that makes a wall of fire may deal damage for several rounds of combat, but what if the wall becomes permanent? A permanent wall will have consequences in your world and in roleplaying much more than a temporary one. When considering temporary actions keep in mind that damage dealt now is always more valuable than damage dealt later, so the potency of the action isn’t just divided among the rounds of the effect, it is also reduced. For example if I have an acid blast that deals one damage each turn for 5 turns, if may seem like it will do 5 damage, but what if the enemy is defeated before the duration expires? And the enemy can still attack me before all the damage is dealt! This acid blast will be worth much less than an attack that deals 5 damage all at once. However, the player faces an interesting choice if its between dealing damage now and dealing even greater damage over many turns.

9.       The setup of the action in terms of its impact on actions in the future. A powerful sword attack that weakens my defenses for a round, a spell that makes my allies move faster, or a spell that makes all my enemies easier to hit are all examples of actions with setup. Typically referred to as buffs and debuffs, setup is used in many RPG systems as the effect of spells. Don’t be afraid to add buffs and debuffs to regular actions a player can take. Can I enter a defensive position, spend my hit points to deal more damage, protect an ally, or paralyze a foe with a well-placed strike? Setup is important because it requires players to think about the impact of their actions over many turns and across their whole team to use effectively.

                Taken together, you can tweak each of these variables to create a dynamic combat system. Make sure that each playable class has choices using each of these variables, even sword fighting classes! It’s no fun to just find the best weapon and use the same attack every turn with it over and over! Next time we will use these variables to create a gritty sword and sorcery system so stay tuned!