Most of us have had the misfortune of reading a bad technical guide that lacks context, presents irrelevant information, and provides code examples that just don’t work. Bad technical guides can cause frustration, confusion, and distrust in your software, support channels, and even your brand—and they can hinder progress and productivity internally. Fortunately, good technical documentation can minimize these pain points, and as software engineers and managers, you already have the resources you need to create it.
There are many different types of technical documentation, from API references to guides, help text to chat bots, and myriad other creative ways companies use text and visuals to support customers. Guides in particular play a big role in how accessible your software is, so good guides are well worth the effort.
If you want to create guides for your software, having a solid content strategy can help you write useful content. This article will walk you through how to develop that strategy, whether you’re an engineer or a technical writer, new to writing documentation or just looking to get more strategic about it.
If your team includes technical writing resources you can partner with, fantastic! I’ll discuss what you can do to start that collaboration off on the right foot. And if you don’t have writing resources available to you, don’t worry. It’s easier to write great documentation than you think—and you don’t have to write a lot to have a big impact.
It’s also important to consider documentation tooling when creating tech docs, but tooling is highly dependent on your company’s needs. Because of this complexity, I won’t focus on tooling here, but you’ll find links to resources for picking a documentation tool at the end of this piece.
Let’s get started.
Identify your audience
Before you start writing, you need to identify your audience: Who are you writing documentation for?
Having a good understanding of your audience will help you write clear and relevant content that maps to their needs. Content that maps to the audience’s needs leads to better comprehension and less confusion and frustration; it presents helpful information that explains confusing tasks and concepts, and anticipates where their challenges might occur.
If you’re not sure who you’re writing for, or if you think the answer is simply “our customers,” try digging a little deeper. Use questions like these to think about your audience:
Is the audience inside your company, or are you writing for external customers?
Are they developers?
What kind of developers are they? Do they work on backend, web, mobile, or other components?
Will they contribute to your code or just use it?
Are they data scientists?
What kinds of tools, languages, and libraries do they use?
Are they non-technical users?
Will they understand basic technical tasks?
How much technical terminology do they need to understand in order to do their job?
If these questions don’t match your audience or your needs, work with your team to brainstorm your own.
Identify the problems you’re trying to solve
People reading technical documentation are usually trying to solve a problem. Once you understand who you’re writing for, the next step is to identify the problems your audience is experiencing (or is likely to experience). These are the problems you or your team’s technical writers will aim to prevent and solve with your documentation.
Whether you’re an experienced writer or you’re just starting to flex your documentation muscles, it’s crucial that you know “the point” of what you’re going to write before you write it. Identifying the audience’s problems before you start helps you scope what you’re writing about and create relevant, actionable content.
When you understand the problems your audience wants and needs you to solve, you can focus on creating content that will improve their experience and support their workflows. I’ve found that it’s much easier to write docs when I know they’re going to solve a problem for someone.
You may already be familiar with the obstacles your audience tends to encounter because of the ways your team compensates to support them. But if not, here are some common scenarios that might ring true for you:
You want customers to start using the cool new software you’ve built, but because it’s not intuitive and there’s no documentation, you have to personally onboard each new customer.
You’ve built software that’s very intuitive, but customers keep asking how it fits in with the rest of your product suite.
A developer who wants to contribute to your repository needs to understand the design and implementation details of your software, but there’s nothing written down.
Your team spends a lot of time answering the same questions about your software over and over again.
Customers are confused about how to complete a specific task associated with your software.
There are many ways to figure out which problems are most relevant to your audience, but one of the best is to collaborate with other teams to gather data. I recommend trying some combination of the following approaches, choosing the ones that are most feasible for your team:
Talk to product designers and UX researchers to see if they have
any user personas that identify your audience’s goals and workflows.
Talk to product managers about customer workflows and pain points.
Talk to technical support and technical account managers, as they troubleshoot with customers regularly and know where they get confused.
If you have any kind of community, forum, or chat support for customers, look through the logs to identify trends and common questions.
Ask your customers directly through interviews, surveys, emails, or other methods. For example, you can ask them:
How was your experience onboarding to Software X?
Were you able to complete Task Y with Software X? If not, why?
Do you have any pain points with Software X?
If you have the support of technical writers, include them in these conversations or connect them with these stakeholders.
Write high-priority content
Once you understand who you’re writing for and the problems your documentation will try to prevent and solve, you can start writing your docs or engage with a technical writer to write them.
Without technical writing support
If you don’t have access to technical writers, fear not! A few well-written documents can have a big impact on user experience.
To write documentation that’s integrated with your code repository, start with a README. Write the Docs, a global community of people who care about documentation, offers a beginner’s guide to writing documentation that walks you through the key README components.
If you’re storing or presenting documentation separate from your code repository, start by creating a basic guide with contents similar to a README. This will include things like:
About
What does this code do?
Why would someone want to use it?
Installation and setup instructions
Examples
FAQs
Remember that research you did earlier? Use that information to write about common questions you identified.
How to get help
Where can users file support tickets?
Who can they contact with questions?
With technical writing support
A technical writer can take the background information you’ve gathered and generate content for you, or partner with you to co-create it.
If you have technical writer support, you can go beyond the README. Start with a quickstart, like Stripe’s Card Payments Quickstart or Google’s Quickstart for Java 8 for App Engine Standard Environment, to onboard new users.
Next, write task-based how-tos, using your research about common problems and your knowledge of your audience’s workflow to define common use cases. What are the tasks people will try to complete using your software? (See the Slack API landing page for an example of how to use clear, concise language to identify common use cases like “send messages and “create simple workflows.”)
Gather feedback
Gathering feedback is a key part of writing good documentation and developing an ongoing content strategy. Ask for input, both internally and externally, on your documentation content and structure early on in the process.
Work with engineers on your team, or another team like technical support, to perform quality assurance. Have them validate each step in your documentation. Next, ask for feedback from your audience through interviews, surveys, emails, ratings, or other methods. On his blog I’d Rather be Writing, technical writer Tom Johnson lists ten ways you can gather feedback from users, including techniques you can use to learn from your audience.
Use this feedback to improve what you’ve written and identify new topics to write about going forward.
What’s next?
When you use the strategies described above, you’re more likely to write content that helps your audience use and troubleshoot your software. And if you’re still itching to do more, there’s a lot you can try!
Once you have more than a few pages of documentation, you’ll want to update the information architecture—how you organize, structure, and label your content. Treejack is a great tool for validating whether people can find what they’re looking for in your documentation. Use this tool at any point in the process to determine the effectiveness of your information architecture.
Finally, we didn’t talk about tooling, but now that you understand how to get started with your content, it’s important to establish a good documentation tooling strategy. The tool that’s best for you will depend on your team’s budget, size, localization needs, format needs, content contributors, and other factors. Some people use static site generators, while others use help authoring tools, wikis, and SaaS tools. There are many options out there, so I recommend doing your research before making a big purchase. If you need help choosing a documentation tool, check out these resources:
If you get stuck while developing your content and tooling strategy, bring the focus back to your audience. Where do they stumble? What will help them succeed with your software? If you keep your audience in mind—whether you’re an engineer, a manager, or a technical writer—you’re well on your way to writing a good technical guide.