Writing Technical Documentation That People Actually Read
The general perception that nobody reads documentation is false. If you write things people want to read, they will read them.
However, while not true, technical documentation isn’t read as often as it should be.
Why not? There are a few reasons, we mention some of them here. In the end the responsibility ultimately falls into the hands of technical writers. Whether you’re a newbie, industry veteran, or somewhere in between, we’re going to share some helpful tips that will breathe life into your content creation process. We’re confident that these will help you create effective technical content that actually gets read.
The Technical Documentation Lifecycle
The basic flow for creating technical documentation is probably familiar to you:
Plan, write, review, and publish.
Every organization adds tweaks to this basic workflow to align with their business goals, personnel dynamics, and individual content creation requirements, yet these four steps are structural mainstays.
I can’t show you how to create technical documentation processes that are tailored to your organization, but we can give you a solid foundation to start from.
Throughout this article, I might mention capabilities specific to our working methods at Ideas Are Human, but the underlying principles apply generally. An important thing to note from the beginning is that methods cannot dictate your processes, but they can certainly influence them.
Research Your Topic
When writing product content, it’s easy to fall into the trap of leaning on your own presumed expertise.
One of the rarest skills in the modern workplace is knowing the right questions to ask and listening for the answer. Technical writers do the tough work, asking the tough questions including the “stupid” questions.
It’s tempting to lean on your own knowledge but be careful. Every assumption carries with it the risk of undermining the entire writing phase. If you assume incorrectly and you are wrong, the best-case scenario is that it is spotted in the review phase. The worst case is the mistake goes public alongside the product.
Do the research, ask the tough questions but also ask the questions that seem silly or dumb at the time. It might feel uncomfortable at first, but you need to swallow your pride and talk to other experts.
We ask the dumb questions because we know that it is often the same question other people had but weren’t brave enough to ask it. Be the brave question asker. The more expert voices you gather for researching your topic, the stronger your content will be.
Finally, if possible, interact with the product as much as you can. While this might not be research per se, it will enable you to ask better, more specific questions.
Create Your Documentation Plan
A Documentation Plan is an official roadmap that technical writing teams build. It creates a structural outline, procedural consistency, and ensures that everyone is on the same page before getting started. Documentation Plans may differ slightly between organizations, but they share many common elements: scope and objectives, time estimates, workflows, and resources, for example.
The Project Requirements Document (PRD) is a common planning document among project managers. Your technical documentation team should be familiar with the PRD and there shouldn't be any glaring differences between the key parts in the PRD and your Documentation Plan. Rather than laying your plans separately from the ground up, coordinate your Documentation Plan with the PRD.
In short, the PRD lists what your product does, how it does it, and the more crucial granular details behind it. From the PRD, you’re going to want to look out for things such as:
Product details
Audience details
Details relating to content requirements
Outputs
Support
Constraints
Releases
Localization
This is not an exhaustive list, but it’s a good start. We can provide you with more in-depth PRDs on request.
Consider Re-use.
How much content does your organization have that is identical or similar enough that it can be reused multiple times in different content deliverables?
When you’ve looked at your content and understood where you can re-use parts of it in different places, re-use will save you the time-consuming task of replicating the same content repeatedly.
Some Content Management Systems (CMS) let you build content in components or blocks. Each block can exist on its own as a standalone component. Stacking several blocks together builds a document, a whole piece of finished content. When a block can be used in more than one document, re-use lets you write that block once and use it in multiple places. Then, if that block needs to be updated in the future, it only needs to be updated in the original block, and those updates will populate everywhere the block is used.
Even when you are creating content for a new product, there will likely be a fair amount of overlap with existing products. Find those overlaps and take note. Don’t think of your blocks of content as being limited to a single document, product, or deliverable. This can be a huge time and money saver. Calculating potential re-use throughout your content database is an initial investment that will bear fruit over time.
Identify Holes in Your Content
Good content means whole content, not content with holes.
Once you’ve identified the opportunities for re-use within your content library, you have a clear view of the remaining gaps in your content.
Identifying these gaps is a critical step. Think about every block of content as a chunk of road or motorway. Your reader is following a predetermined route of knowledge that you’ve laid before them. Now imagine that suddenly they come to a large gap in the road where there should be a bridge.
Technical content is similar but much more subtle. Getting users to understand a direction is a task that can’t afford gaps. Frustrated users are much more likely to search for answers elsewhere, like YouTube videos and online forums, or search for products elsewhere.
Taking an occasional content inventory is necessary for identifying content gaps that may lead to user experience pain points. Users will often directly tell you where something is lacking, unclear, or difficult to understand . Use their feedback alongside your own content self-analysis and close those knowledge gaps.
Write, Review, Test, and Deploy Your Content
Get it done. Get it done well. Be proud of it.
Finally, the part that you love. Writing. I’m not going to use a lot of space telling you how to do a job you know how to do, just some baseline things to remember when writing:
Remember your audience and write for them
Avoid knowledge assumptions about your audience
Focus on the BLUF (bottom line upfront)
Be concise, but don’t sound robotic
Think about tagging any potential variable content (product names, company names, feature names, etc.) that you may need to access down the road
Once the content is written, or perhaps during the writing phase, get the eyes of experts involved. Make sure that during reviews, the right people see the right documentation. Just like finding the right experts during research, you also need to find the right experts during the review phase.
When the right eyes see and review the right content, your job as an editor is much simpler. When you’re done there, take a moment to see what your content will look like live. Preview test runs will help identify any remaining errors, however minuscule. Plus, you can see how great your work looks and be proud of it before sending it out to the world.
6th November 2023