Steps to Create Technical Documentation Lles Ferrando

Sumario

1 Steps to Create Technical Documentation
- 1.1 When, why, and how to properly use technical documentation
- 1.2 How to plan, write, and deliver technical documentation that works
2 Véase además
3 Enlaces externos

Steps to Create Technical Documentation

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

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.

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.

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”

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 equipment? 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 emplate 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
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.

Step 3: Create the content

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:

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.
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.
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.”
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.

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

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