<-- home

Documentation

Published: October 30, 2017



About

I’ve written this essay to share with others some of the things I think about when I write my own technical documentation, and some of the things I look for when reading others’ documentation. I was motivated mostly by my peers and leaders, who more and more have been asking me to review their documents. I’ve found myself giving the same feedback over and over: how should I review this document, what context do I need, among many others.

I’ve tried to capture some of the things that I think make a really good technical document, and in some cases provide frameworks or tools that you might be able to use to help write good technical documents. The considerations and thoughts captured here aren’t a checklist of things that you must think about to write a good document. Instead, they’re a list of guidelines and suggestions that I think will head you in the right direction.

I’ll talk about what I call a document’s ecosystem: a discussion of the different types of documents, how they serve different audiences, and how continuity in an existing documentation space is important. This section establishes why knowing your audience and existing space is important. Next, I’ll talk about what the anatomy of a good document looks like: good documents establish context, exhibit some sort of structure, and are consistent. Last, I drill into a few gotchas that are important for writing a good document. If you read this document, you’ll be left with a fairly good idea of how I try to write and review technical documents.

Before going further, I should also tell you what this document is not. This document is not a guide or suggestion on how you should go about engineering a documentation organization, or how to culturally change your engineers to start writing documentation. For this, consider exploring other resources like TechDocs at Twitter.

Ecosystem

Situational awareness is important, and this section talks a little bit about what it might mean to be situationally aware when writing your document. You should think about the topics discussed in this section before your start writing your document.

Types

One of the first decisions you must make before starting to write your document is choosing what type of document you intend to write. Each type of document is useful in its own right, and leads into the topic of targeting your audience. Choosing a document type gives you a framework to decide what sections are necessary and which are not.

For example, consider a design document. A design document would likely have sections on prior work, alternatives that you considered, user stories, and much more. A design document shouldn’t have sections on implementation, instructions for using the tools, or issue to resolution instructions. Likewise, your user manual shouldn’t discuss implementation. Every document type has a purpose.

Often, one generates each of these documents when the lifecycle of the project necessitates it. For example, during design phase, you write design documents. After implementation, you write implementation documents. While maintaining, you probably write user manuals and issue-to-resolution documents. During the full lifecycle of a project, you’ll end up writing many different types of documents.

I typically discourage people from writing documents that serve two purposes, simply because it’s challenging to maintain context and structure in these cases, both of which I’ll discuss later. At first, it may feel tidy to add your design and implementation sections in the same document, but in the end, it makes your document too hard to follow. One strategy I suggest when confronted with this use case is to add a landing page, from which you can direct different audiences to different pages. This helps with discoverability and forces structure into your document.

Some of the types of documents that I know of are the following.

  • Notes - You generate these during meetings, prototyping sessions, and other such sessions. The audience for these documents is likely the same folks that generated them, so appeal to yourself.
  • Status Update - You generate these on an interval to provide transparency into the progress of a technical project. The audience for these documents are non-experts, like your managers or technical leaders.
  • Design Document - You generate these for technical experts for a number of reasons, but mostly for review and for reference. You may use these documents as a sort of Request For Comments (RFC) or use them as a reference for why someone is the way it is some number of years in the future.
  • Implementation Document - You generate these for project owners. The audience for these documents is both experts and non-experts alike. An expert uses these documents to make big decisions during maintenance. A non-expert uses these documents to onboard themselves with the structure of the project.

There are many, many other types of technical documents that exist in the wild, so many so that I think it would be hard to list them all out here. In fact, I’ve left out some very important types, like Request For Comments (RFC) and user manuals. This short list is intended to get you thinking of the different types, how they identify your audience, and why purpose is important to consider up front. These types are also the types that I’ve encountered most frequently in the workplace.

Audience

Choosing the type of document is the biggest indicator of who your audience is, but there other aspects of your audience that are important for you to consider. Fundamentally, as a document writer, you’re an educator, and hence your goal is to educate people. Different people learn different ways, so you should be considerate of the different ways that people learn.

Writing effective design documentation (like design itself) is really all about making sure you serve the needs of your audience. Ryan

Consider the different types of learning styles: visual, auditory, reading/writing, and kinesthetic. Taking into consideration all the different types of learning will help you build a robust document with examples that appeal to each type of learner. For example, well written documents might include a mixture of graphics, mnemonics or other language designed to be read aloud, well formed prose that tell complete stories, and more. I try to appeal to kinesthetic learners by relating technical concepts back to real world concepts, since that type of learner is difficult to appeal to in written documents.. This might be as simple as providing examples to your otherwise abstract concept. Most people are mixtures of the above. Balance is key.

When you enroll in a curriculum of some sort, that curriculum discusses what you’ll already need to know and what you’ll take away from the program. Be open and honest with your audience with what you expect from them. Consider stating what prerequisites the reader should already have satisfied. It’s okay to tell a reader that they should be experts of other fields before reading your document, e.g., that they have an understanding of linear algebra or have read another document. Likewise, do tell the reader what goals they should expect to achieve while reading the document. Being forward with the knowledge that the reader should take away from the document foreshadows to the reader what sections they should really focus on. It even might tip the reader what section is most valuable to them for their specific purpose. If there is a really important or complicated topic nested in your document, say so.

There are certainly more things to think about than just this, but I think acting like an educator, being considerate of the different types of learners, and being open and honest about pre and postconditions, give you a basic framework to work with your audience effectively.

Aside from learning styles, you should be cognizant that within a single audience, there may be multiple levels of interest for a given topic. For example, in the workplace you might have a vice president, a director, and an engineer, all consuming the same document. Each different role seeks a different level of depth. I like to think about the problem of satisfying all audiences as a layering problem. One strategy I employ to solve this layering problem is to be able to discuss the same thing several times, each time adding additional depth. This strategy seems synonymous with having an “elevator pitch” for your idea, except that you have an “X pitch”, “Y pitch”, and “Z pitch”, for the vice president, the director, and the engineer, respectively.

Of course, saying that all vice presidents want only a cursory understanding of the topic and all engineers want a deep dive of the topic isn’t correct. The value of providing different levels of depth for your audience comes from giving the reader the ability to choose what level of granularity they’d like to go.

Finding a graceful way to do this might be hard, since you don’t want to end up repeating yourself over and over at different levels of granularity. Breaking a complex document into multiple documents is one strategy I use to solve this layering problem.

Conceptual Integrity

Parnas in The Mythical Man Month described a role called the architect. This person is chartered with the responsibility of maintaining “conceptual integrity” of a project or idea. Consider identifying who on your team or organization best fits this role and ask them to review your document. Even better, ask for them to own factoring the document into the best place possible. This will help keep the documentation base clean, concise, and [hopefully] avoid duplication. The act of getting an external review with the intent of figuring out where your document fits into the larger ecosystem might also act as a signal to others that now is time to update their own documents. The last thing you want are dangling references to your document!

As an aside, note that people often wear many hats, so don’t give up if you don’t have a dedicated architect to review your document, just ask other document-writing engineers to review it. On every team I’ve worked with to date, it’s everyone’s responsibility to maintain conceptual integrity.

Ensuring that your document is correctly placed in its ecosystem should make your document easier to discover, which at scale, is a huge issue. How many of you have struggled with discovering documentation in the wild or workplace? Remember, just like a linked list insert operation, that your job isn’t done until you update the previous node to point at you.

Anatomy

This section talks about what makes up a good document and some of the frameworks or tools I use to force myself to write an anatomically correct document.

Context

Per Merriam Webster’s dictionary, context is, “the parts of a discourse that surround a word or passage and can throw light on its meaning.” As an educator, it’s your goal to teach our readers something. Per the definition, we can’t really reach anyone anything without first establishing context. This is the most common pitfall that I’ve seen in documents: they don’t establish context.

A lot of people get to “expert” level in a lot of different ways and paths and assuming previous knowledge is dangerous.

When pondering why this is so hard to do, it usually boils down to the fact that the document writer is also the individual most immersed in the universe they’re documenting. Removing oneself from the context of their own experience is perhaps one of the more challenging preconditions for the document writer themselves. Luckily, though, there are a few methods and tools that I’ll share to help one accomplish this.

One common strategy to help the author establish context is to write every section using these three steps:

  • Tell the audience what you’re going to tell them.
  • Tell the audience what you want to tell them.
  • Tell the audience what you just told them.

This three step program decomposes communication down into three distinct steps that you can focus on individually. The first step is the one during which you should establish context.

While telling the audience what you’re going to tell them, assume that everyone knows nothing. It’s during this step that the burden of education is on you. Ensure that you define your terms, tell your audience who they are, and define preconditions necessary to understand what you’re going to tell them. During this step, make sure that you make the barrier to entry to education as small as possible. Provide resources to other documents, and reduce the number of hops needed to get to those resources. It’s very appropriate during this stage to not only tell the reader what, but also why the what is important. Again, assume that everyone knows nothing.

During the second step, reference the context that you’ve established. For example, if your document is describing the design of a new solution, then the prior system and its deficiencies should be well explained in the first step. If this document didn’t include this context, the barrier to entry to learn about the prior system is far too high, in which case your document is nothing better than a dangling pointer. Again, the burden is on you, the writer, to make this easy.

During the third step, you establish what you’ve said and why it makes sense. If there are decisions to be made or debate to be had, this is the section where you should indicate that. This is a perfect opportunity to call on the areas that you think need feedback, and those that do not. Keeping the reader on task here should prevent bikeshedding.

Sometimes you may find that it’s necessary to tie together otherwise disparate ideas. If you find yourself in this position, consider using a diagram to tie together the concepts. It’s amazing how powerful a simple diagram can be to tie together ideas.

Structure

In computing we always deal with data structures. They help us organize data. Wherever possible, I think that information can and should be organized as such. Organizing your information into a, for example, a directed acyclic graph (DAG) forces you to focus on the topics (the nodes) as well as the transitions between them (the edges). It’s an encapsulation of the what, the how, and the when! In some ways, it forces you to tell a story. Your document should follow some progression: you start with a big picture, identify subtopics, discuss each subtopic, and so on and so forth. Implements for representing your data structure could be as simple as pre and post ambles that relate the prose to others, or establish pre and post requisites.

Readers are like re-entrant codes riddled with long jump instructions. They don’t always read your document linearly as you might have intended. They will jump between sections, might read the document backwards, will only read every other section, or will just fault and not read anything. Insuring your document has structure with an obvious way to progress through the document, with internal breadcrumbs to connect each section, will equip the reader with the tools to digest the information in the document regardless of how they read your document. A nicely written document will eventually start to look like a doubly linked list or some other fancy data structure you build things with. Don’t use a heap though.

As the amount of content grows in your document, so should the amount of context that you find yourself setting. As the amount of context grows, how do you maintain context of your context? Information management is a field in and of itself, but I think the following is all that is needed to maintain your contexts: the table of contents.

Writing a technical document without using an outline is like trying to navigate the New York City Subway System without a map. You can end up anywhere. Bob

If you’re not making use of a table of contents, you should start. Most modern platforms support some level of table of contents generation. If they do, leverage the platforms support for it. For example, if you’re using Atlassian’s Confluence, use headers and subsections; if you’re using Github’s flavor of Markdown, use hashes. There is nothing worse than a half baked implementation of a table of contents. You see this when someone uses ordered and unordered lists to try and simulate a table of contents. Giving labels to your sections and subsections is important! Make an effort to ensure your table of contents is consistent and looks nice.

Your document’s table of contents is the lattice on which your entire document is built. It’s a framework that in and of itself tells the reader what you’re going to tell them (see the previous section). On several occasions, I’ve sought review only of my proposed TOC, to make sure the intended audience would be happy with the document after I write it.

The table of contents is a tool for the author. As the author, you can use the TOC as a way to establish a contract with the audience. The TOC, even without content, discusses what you’ll talk about and might even be able to establish the point of the document. It’s the elevator-pitch version of the document. On several occasions, I’ve sought review only of my proposed TOC, to make sure the intended audience would be happy with the document after I write it. I believe wholeheartedly that a standalone TOC is a reviewable deliverable.

A second use of the TOC is to help the author gauge the complexity of their document. Use your table of contents as a tool to expose accidental complexity: if your document exhibits no structure, it’s likely that your solution exhibits no structure. As your document grows in complexity, so does your table of contents. Just like you measure program complexity with metrics such as McCabe complexity, you should also measure your document’s complexity with the amount of subsections that you depend on to convey your idea. If you find that your document’s table of contents has become a heavily nested, you may want to consider refactoring your document to make it less complex. If you cannot refactor because you’re describing an inherently complex problem, consider breaking the document into multiple documents that can focus on distinct and consumable subproblems.

Your document’s table of contents is a tool for you, the writer, to stay organized and a map for your reader.

Consistency

Perhaps it is not worth saying, but consistency in everything I’ve shared this far is of pivotal importance. In the words of Jeff Weiner, trust is everything.

Trust is the bedrock of everything that we do, quite literally. … An old friend once taught me that trust is consistency over time. It’s a simple formula for a complex thing.

If you are consistent, your readers can trust you. If your readers trust you, and you leverage that, you can teach them how to interpret and navigate your document. This is super powerful! This phenomena can be leveraged to help your users know which sections are important to them, to help them find content that is most important to them, and more.

Keep your document consistent by removing ambiguities, defining and using terms consistently, establish a system for linking your ideas together, and whatever else you can possibly think of to maintain consistency. When adding documentation in an existing ecosystem, be sure to be consistent with what already exists!

One practice you can follow to help maintain consistency in your document, is to always write a first draft. Plan to rewrite what you just wrote. During your first draft, don’t worry about many of the intricacies I’ve talked about this far, just generate your content. After you have your content, you can identify the parts that need refactoring, the parts that can be consolidated, the best way to factor your table of contents, and so on. Don’t get attached to your first draft, since you’re going to rewrite it.

Mechanics

So far we’ve covered the most important aspects of writing a good documentation: having a strong understanding of the ecosystem that you’re writing within and the anatomy itself of a good document. This section is more mechanical and calls out some of the nuts and bolts of writing. In aggregate, documents that don’t have sound mechanics tend to be of low quality.

Language

During university while taking a theory of computing class, it was with great satisfaction that I learned English is not a formal language. No natural language is a formal language. To my dismay, this citation never convinced instructors that my use of bad grammar didn’t matter.

Writing is obviously the most important part of technical documentation, and sometimes I think technical writers, myself included, underestimate it. Context rich discussion, complex diagrams, and superb structure are undermined by poor grammar, missing arrows, and run on sentences. Luckily, this is an area filled with ample amounts of prior art and classroom curriculum.

A few of the best resources I’m aware of are:

  • The Elements of Style
  • The Gregg Reference Manual
  • The Curious Case of the Misplaced Modifier

The best way to get better at writing is to write. There are a number of fun platforms available to you to write to your hearts content. Some of my favorites in stack order are:

  • Jekyll
  • Medium
  • LinkedIn
  • Wordpress

Writing can be pretty scary. If it is as scary to you as it is me, you might opt to write an anonymous blog, or setup a privately hosted Jekyll instance. Whatever you choose, the simple act of writing will make you a better writer.

Maintenance

Writing documentation that lends itself to maintenance is really hard. Often, by the time you’ve finished your design, implementation, user manual, and other support documents, things have all changed. It sometimes feels that agile development flies in the face of documentation, which can simply never be up to date. Right?

Despite the fleeting feelings that might come with keeping your documentation up to date, trying to make your documentation as sustainable as possible will go a long way, and your peers will thank you for it. Anticipate from the beginning how your document will embrace change and revisions.

Two of the most important pieces of making a document sustainable are defining ownership and lifetime of the document. Defining who owns a document as well as who can be contacted with questions lowers the barrier to entry to asking questions or making updates. Defining the lifetime of the document is also an underappreciated feature. Defining a lifetime means sharing with users dates of inception, how long the document is intended to be valid, etc. For example, if a design document is meant to be valid as long as a certain condition exists, say so. This will give future readers the context to know whether the document is valid or not. If there is a hard deadline at which the document becomes inapplicable or out of date, definitely say so.

Often technical documents include a number of attachments. One of the most damning attributes of a document is out of date attachments that cannot be updated. Avoid this attribute like the plague. Force yourself to make your attachments, diagrams, etc., available for modification somehow. A document that is out of date or impossible to update (e.g., because diagram source is lost) undermines the purpose of the document to begin with.

Peripherals

It’s the little things that make a big impact, en masse. Here I want to share a laundry list of things that I think matter enough to write about them.

  • Do indicate when a document is a work in progress.
  • Do get your documentation reviewed.
  • Don’t overuse archaic words that your readers are going to look up.

Closing Thoughts

Treat the suggestions present in this document as just that: suggestions. I myself never follow all of my own advice, and never find one writing framework works for everything. As Captain Barbossa wisely said, “the code is more what you’d call “guidelines” than actual rules.” I feel like that statement best captures what I’m trying to deliver in this document.

The code is more what you’d call “guidelines” than actual rules.

If you’ve read this document, you now know of most of the mechanical things that I think of when writing a document. None of the things I’ve talked about have much to do with the content itself, just strategies and tools that I use to keep me honest: identifying my audience up front, establishing context, using a table of contents, staying consistent, seeking review, and much more.

Citations:

  1. http://boxesandarrows.com/six-tips-for-improving-your-design-documentation/
  2. https://opensource.com/business/15/5/write-better-docs
  3. http://www.lifehack.org/articles/communication/20-books-help-you-polish-your-english-writing-skills.html
  4. https://medium.com/@limedaring/five-tips-for-improving-your-technical-writing-and-documentation-47353723c8a7
  5. https://web.mit.edu/course/21/21.guide/eff-char.htm