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.