« Back to Planio Blog

Jory MacKay on November 15, 2018

Jory MacKay

Jory is a writer, content strategist and award-winning editor of the Unsplash Book. He contributes to Inc., Fast Company, Quartz, and more.

November 15, 2018 · 11 min read

For as long as we’ve had tools we need help using (and language to talk to each other), we’ve had technical documentation. (Don’t believe me? The first example of technical writing in English dates back to the Middle Ages when Chaucer wrote a guide to the astrolabe—a device used for measuring the distance of stars).

Technical documentation refers to any document that explains the use, functionality, creation, or architecture of a product. Think of it as a nuts-and-bolts “how to” guide for your users, new hires, administrators, and anyone else who needs to know how your product works.

But while that sounds pretty straightforward, the results rarely are.

Technical documentation can quickly go from “here’s how to use this if you’re unfamiliar and have limited experience” to “here’s an unedited transcript of everything our developer told us about this obscure application of our API.” One’s going to get you using the product right away, while the other will make you go cross-eyed.

Technical documentation isn’t just about capturing information. It’s about presenting it in a way that’s easy to read, usable, and actually helpful for your audience. So if you don’t know where to start, here’s our short guide to making technical documentation that’s actually helpful.

But first, a quick overview of this article:

When, why, and how to properly use technical documentation

Technical documentation helps an intended audience use your product, understand your processes, and get unstuck. Whether that audience is end-users, administrators, colleagues, or technicians doesn’t really matter. What does matter is that it’s clear, searchable, and helpful for them.

Great technical documentation empowers your users, not frustrates them. It’s an integral part of not just customer support, but brand building and trust. Users seek it out when they’re most in need. And if it’s not there for them, they’ll start looking for alternatives.

Here are a few examples of where and how you can use technical documentation:

• End-user support: This means things like user guides, release notes, online help systems, training programs, or operating procedures—anything that helps users use your product.
• Marketing support: Anything that’s product-focused and used to market your company (like explainer videos, presentations, or technical landing pages)
• Development support: This could be functional and technical specifications, software development guides, or simply procedures and tools to help your developers do their jobs.
• Organization support: Information about your company, structure, procedures, workflows, policies, and anything else teammates need to know to do their jobs.

While back in the day most of these documents would come as physical guides for users, today, most technical documentation should be available on your website or help pages (which is also great for SEO).

How to plan, write, and deliver technical documentation that works

So how do you create these clear, concise, wonderfully useful documents?

First, you need to decide who is going to be responsible for them. Technical documentation is usually either written by a subject matter expert (i.e. someone who knows what they’re talking about), or a technical writer who’s been trained to translate complicated product knowledge into content that’s more easily understood by the end users.

Once you’ve put your team together, writing technical documents comes down to a few simple steps.

Step 1: Do research and create a “Documentation Plan”

As the old saying goes: “Write what you know.”

Every technical writing project starts with research. It might sound obvious, but knowing the purpose and scope of your technical documentation beforehand will save you a ton of time and energy (and headaches).

If you’re not the subject matter expert, this might mean doing some internal interviews and building relationships with the technical team to get a stronger grasp on the material (and to avoid what senior technical writer Will Kelly calls “Mission Impossible” technical writing projects). Or, it might be as simple as going through existing resources and guides and doing a short audit of what you have and what’s missing.

All of this information goes in what’s called a documentation plan—a short outline to help guide you through the project. Here’s what you should include:

• Goals: Simply put, what do you want people to be able to do? Is it to use your product? Find help documents quickly and easily? Learn how to use certain aspects of your tool? Let teammates request resources or order fulfillment? Having and knowing a clear goal is essential to writing good technical documentation and will help inform everything you do.
• Existing resources: What’s currently out there? Are you updating or merging current resources or starting from scratch? Are there old, outdated versions that need to be killed? Do a quick audit and find anything and everything that will help you write or confuse your audience if they find it.
• Style guides: Some industries require you to write technical documentation in a specific way (like the Plain Language guidelines for government sites or Simplified Technical English for aerospace, aviation, or defense companies). In other cases, your company might have a style guide that explains what language to use, how to talk to users, and even grammatical styles.
• Outline of topics: What topics and subtopics will you be covering in your technical documentation? Think of this as a table of contents and try to list out every major section and subsection you think you’ll need.
• Tools and management: What software, tools, or websites will be used to create and manage the documentation? Link to relevant style guides.
• Deadline and final deliverables: When is it due and what format will it be in? Technical documentation is as much about structure and delivery as it is content. And knowing how the content will be presented before you start will tell you what you need and where to put your efforts.

Step 2: Structure and design

The goal of any technical documentation is to be usable. And a huge part of that is making it structurally logical and easy to navigate. Before you even get into creating content, you need to think about how that content is going to be presented.

This means thinking about both on page design (how the individual technical documents look, what’s included in them, and the hierarchy of information) as well as the navigational structure of your document (what order is information presented in, how do users move around and navigate, what documents are linked or connected, etc...)

Here are a few quick tips for each:

Use templates or “schemas” for consistent on-page design

Have you ever flipped through a user manual or opened a help document and instantly knew it was bad?

Most likely this wasn’t due to lack of information, but poor structure. The human brain has a thing called cognitive fluency, which refers to how easily we’re able to understand the information placed in front of us. If it’s hard to read (through poor design and layout) we experience the content as difficult or less useful.

That’s why technical documentation is structured content. In order to be useful, it needs to be presented in a way that’s easy to parse quickly and find what you need.

In most cases, this means using some sort of template or schema (a blueprint of how your data will be constructed). For example, your technical documentation template might look something like this:

• Title: What is it?
• Subtitle: Additional information
• Overview: What will you learn
• Table of contents: Internal navigation
• Features: Each section of the document
• Read next: Related documents that might help the user

Here’s an example using Planio wikis:

In this template, the user knows exactly what they’re reading, gets a short overview of what the document covers, and then has a table of contents outlining each step so they can jump to the most relevant one right away.

Not only will keeping things organized like this help your users find information more quickly, but it will let you know if you have all the information you need to keep your content consistent.

Create a simple, logical navigation structure

Your project as a whole also needs to be organized in a way that makes sense and can be quickly parsed. What are the main topics that people will be searching for? Under each of those, what specific questions or documents will they be looking for?

Hierarchy is incredibly important here, which is why Planio’s wiki lets you define your own structure and create parent-child relationships. Here’s what that might look like:

Notice how each main category has relevant subcategories and then specific questions? This way, finding the information you need is quick and easy. No more aimless clicking and searching.

Step 3: Create the content

Alright! With your documentation plan and structure in place, it’s time to get serious about creating your technical documents.

Like any writing project, the easiest way to create technical documentation is to follow a few steps rather than try to dive right in and start writing. Here’s the easiest way to make sure what you’re creating is useful, valuable, and clear:

Start with a draft

Using the information in your documentation plan, you can start to sketch out a high-level outline for each of the topics you’ll be covering. This is a great place to find holes in your planning and research as they’ll become painfully obvious as you start to create an outline.

Once you’ve finished the outline, gather the rest of the specific content you’ll need for each topic and any supporting graphics. If you get stuck along the way, leave a placeholder or internal note to come back and fill it out.

Also, if you’re writing a “how to” or help guide, you should follow along and do a self-review to make sure everything you’re writing can be done. Always remember that your technical documentation is for the user. If they can’t easily navigate, read, and use what you’re creating, it’s useless.

A few quick tips on writing well:

Writing doesn’t come naturally to everyone. Especially when the subject matter is dense, technical, or complicated. But because your ultimate goal is clarity, you’ll want to follow a few simple rules:

1. Write like a human: Use simple, clear language whenever possible. We’ve all read those documents that sound like Google Translate gone wrong. If you find yourself slipping into awkward sentences or complicated language, step away for a few minutes. Sometimes coming back to a piece of writing after a short break is all it takes to refresh your mind.
2. Remember, your readers aren’t you: The golden commandment of technical writing is thou shalt not assume. You might think you’re being obvious, but you have to be keenly aware of the knowledge level your audience is at. Don’t assume they know even half as much as you.

   The golden commandment of technical writing is “thou shalt not assume”. You might think you’re being obvious, but you have to be aware of the knowledge level your audience is at.

3. Write as much as needed to be helpful and not a word more: Short writing is good writing. Use formatting to break up large chunks of text and keep clarity front and center. As Amazon technical writer Tom Johnson writes: “A good technical writer reduces the word count to just the right brevity without being obscure.”
4. Remember the power of visuals: It’s another cliche, but pictures really do say a thousand words. Whenever possible, visualize what you’re saying rather than try to explain it.

Use the 30/90 rule to get feedback

Along the way, you’ll want to get feedback on your technical documents, both as a gut check to make sure you’re not getting overly complicated as well as to ensure you’re explaining things properly.

Unless you’re an expert in the topic you’re writing about, it’s a good idea to have a subject matter expert (SME) come in after the first draft and final draft to review. Giving feedback is a skill in itself. And when it comes to technical documentation, one of the best ways to frame it is as what Jason Freedman calls “30/90 feedback”.

At 30% done (your first draft or outline), you’re not asking for in-depth feedback or reviewing or typos and grammar, but rather for the reviewer to engage in the broader outline, flow, and structure of the document. While at 90% done (your final draft), you’re asking them to go over the documentation with a fine-tooth comb and nit-pick any issues.

Building in a steady schedule of reviews will make sure you don’t have any nasty surprises when you go to submit your final documentation.

Get peer reviews and make revisions

In between reviews from the SME you’ll also want to set up peer-review sessions to make sure the content is accessible and usable to your intended audience. Ask a project stakeholder or someone outside the project to go over your documents and pick out anywhere they get lost or confused.

It can be disheartening to hear that someone doesn’t understand what you wrote. But always remember to keep the user front of mind. If someone within your company got lost following your directions, a total outsider doesn’t have a chance.

Edit, edit, and edit some more

Good writing comes down to editing. With your feedback and revisions in place, break out your style guides and either edit the documentation yourself or take it to a technical editor who can make sure the language has a logical flow and is consistent throughout. Whenever possible, you should try to get a second set of eyes on your content.

Planio wikis are especially powerful for editing with version control, history, and roles and permissions to make sure you and your team stay on top of who's written and edited what.

Planio wikis are especially powerful for editing with version control, history, and roles and permissions to make sure you and your team stay on top of who's written and edited what.

Step 4: Deliver and test

Once your documentation is put together and live, it’s time to get some real-world feedback on it. Unfortunately, this step often gets skipped during the development of technical documents (as most companies don’t have the time and resources or think it’s not worth it). But, as we’ve said multiple times in this guide already, technical documentation is all about the user. If it doesn’t work for them, it’s a failure.

Start with a simple safety check. This means going through any documents, directions, or use cases that could potentially cause someone’s computer harm if done improperly. This could mean exposure of personal data, deleting of important information, etc… You’ll know best based on your product.

As part of the safety check, you should make sure to revisit the topics on basic functionality and terms explained as these are the core of your documents and should be precise.

Next, do a navigation audit. Remember that your document structure is key. If users can’t get around them easily they’re just as useless. Check for broken links and make sure navigational elements are working and obvious (if you don’t have any, you’ll probably want to add some).

Lastly, check for usability/UX issues. Are users getting lost or confused? Are they not getting the answers they were looking for (or thought they were getting based on headlines or navigation?) The experience for the user comes down to more than just what you’ve written. Take the time to work with outside testers to make sure that when real users come to your documents, they leave happy.

Step 5: Create a maintenance and update schedule

At this point, you’re ready to push your documentation out into the world. But if you think your job is finished, think again.

Technical documentation is living content that needs to be reviewed and brought up-to-date with new product releases or updates. As part of your job, you need to create a schedule for regular maintenance (go through the test phases again) and updates.

Technical documentation is living content that needs to be reviewed and brought up-to-date with new product releases or updates.

The 4 additional qualities of great technical documentation

If it’s not clear by now, the one thing your technical documentation has to have is clarity. Ease-of-use is your top priority. But it isn’t your only one. As you put together your technical documentation, aim for these 4 other qualities:

1. Efficiency in development and use: Duplicated content, unorganized structures, and unclear processes can kill technical documentation. Use a tool like Planio’s wikis to keep content organized and efficient.
2. Up-to-date information: There’s no point in giving your users inaccurate information or showing them dated screenshots that don’t look like what they’re dealing with. Keep your technical documentation up-to-date and current.
3. Consistent design and structure: Every time you get in contact with your users is a time to build your brand. Keep consistent with your design, style, and tone across all online documentation.
4. Accessible anywhere: Mobile is taking over the world. Your technical documentation, just like the rest of your website or app, needs to be responsive and provide a great experience for users on all devices.

Technical documents can empower or frustrate—the choice is yours

It’s easy to downplay the role technical documentation plays in your company’s success. But the truth is that the easier it is for a user to find the information they need to use your product, the more they’re going to enjoy it, stay loyal to your brand, and recommend you to other people.

Technical documentation is more than just another task to be checked off your list. It’s an essential part of supporting the people that support you. So take the time to follow this guide, create a clear, accurate structure, and write content that turns your users into product superheroes.