No product is complete without the technical documentation that lets users learn more about the features and answers their questions.
Since describing the entire product and anticipating user questions is no small feat, we’ve created a guide to lead you through the process of writing technical documentation.
We’ll explore the steps you have to take in preparation for writing and see what’s left to do after clicking the publish button.
So, keep reading to find out how you can write technical documentation users will want to read.
Step 1: Start With Research
A thorough research session should be the starting point of your writing process.
Knowing what your technical documentation aims to do and how you will write about the product will help you construct a better, more focused document creation process. We wrote an article about what is technical writing, and we develop the concept of ''the goal of technical writing''
If you’ve participated in product development, research may sound like the writing step you can do without. Still, you shouldn’t forget that good foundations make the actual writing smoother.
So, it seems like tech writers are onto something when they say that technical documentation requires much more research than writing. Here are some business benefits of creating technical documentation.
We know that the recommendation to “start with research” may sound a bit vague, so we’ve compiled a table that could help you break down the research process into actionable steps.
Here’s what you should look into before writing.
Essentially, you can start researching by examining the state of the current documentation you have on hand. You might wanna learn about these skills needed for good technical writing!
That approach could save you from writing a significant chunk of documentation anew when only an update would suffice.
The research will also provide you with a direction in writing.
For instance, if you find that general audiences will be your primary readers, you know you’ll have to simplify the language you use.
Here’s an excellent example of uncomplicated language used in a user guide/ user manual intended for non-technical audiences.
As you can see, the onboarding steps are laid out in plain terms and accompanied by screenshots.
On the other hand, if you’re writing API documentation, you’re addressing a highly technical audience and will need to spend more time creating code samples, like in the following example.
All in all, it’s vital to decide on the defining parameters you’ll reference during writing, which you can’t do without proper research.
However, there’s one more step you need to take before you start writing technical documentation. Let’s learn about designing and structuring the docs.
Step 2: Design and Structure the Documentation
Once you’re done with research, it’s time to celebrate—you’ve successfully laid the foundations for your technical documentation.
Next, you should think about the documentation structure and draft the outline. That way, you’ll be able to present information in a logical and coherent manner.
In case you’re not sure how to structure your documentation, you can start by looking at it from a reader’s perspective.
For instance, when you install a new app, you usually first set up the basics before moving on to specialized features.
That’s exactly how ChartHop, an HR tool, organizes their product documentation.
In the image above, you can see the table of contents on the left side. It starts with the general information you need to start using the solution.
After the setup instructions, users can jump to documentation about features such as visualizing, tracking employee performance, headcount planning, and more.
ChartHop is an example of a well-thought-out information hierarchy because the documentation starts with general information applicable to all users, and then branches out into specifics that each user can browse according to their needs.
Besides planning the outline, you should also design the structure of individual documents. Let’s take a look at Stripe’s API documentation to see a good role model.
Stripe covers all vital API elements throughout the entire documentation. Each document contains a description, method, code example, and parameters.
Such a consistent structure helps readers find the info they need anywhere in the documentation.
If a consistent structure sounds like something you’d like to implement in your technical documentation, you should consider writing using templates, such as this one that comes with Archbee, our documentation writing solution.
Templates ensure the uniformity of content and ease of navigation.
Once you set up a template, you no longer need to think about how you’ll organize your next chapter—you’ll have a reliable base that you can adjust whenever you need.
To sum up, defining the document structure is a crucial step in technical document creation that helps you organize the content methodically, so make sure you don’t skip it even if you’re pressed for time.
Step 3: Write the Content
After all that preparation, it’s time to move on to the main event: writing your technical documentation.
By this point, you’ve already defined what you’re going to write.
During the research and structuring phases, you’ve reinforced the knowledge you had about the product, so now is the time to take a step back and consider how you can capture the knowledge in a way understandable to those seeing the product for the first time.
In other words, you should avoid assuming the users know how to do something. Instead, it’s better to spell things out, at least for the first time when you’re referring to an action or an item.
❌ SSH into a server
✅ connect to a server from your local machine
Speaking of spelling, it’s wise to use technical writing style guides during writing. These helpful resources will help you express your ideas clearly and keep your readers engaged.
They will not only help with the most appropriate grammar choices for writing technical documentation; such guides also contain valuable stylistic recommendations that make your writing easier to follow.
Take this excerpt from Google’s documentation style guide as an example of how writing guidelines can improve the quality of your documentation.
You can find a list of our favorite style guides here.
It’s also essential to find the balance between brevity and verbosity. According to Tom Johnson, a documentation writer at Google, it’s better to keep the language minimalist.
“A good technical writer reduces the word count to just the right brevity without being obscure.”
Also, you shouldn’t forget that writing technical documentation involves several rounds of editing. Keep in mind to avoid these common mistakes in writing technical documentation.
If you want to avoid the confusion that can arise when multiple people edit the same document, your writing solution should support collaboration.
Our product documentation platform, Archbee, lets you tag and mention all contributors within the docs, facilitating the editing process.
Now, as you’re nearing the end of writing and editing, you can already imagine the happy faces of users who have solved their problems using your documentation.
But to truly ensure that readers can use your technical documentation, you have to scroll back to page one and test each instruction you’ve provided. Check these 6 types of technical documentation.
Step 4: Test Your Documentation
If you want to ensure that your documentation is operative and readable, your next step should be testing.
Scrutinizing the documentation for usability and organizational issues will help you present the readers with instructions they can easily implement.
However, writing the documentation will get you very familiar with the matter—maybe even too familiar, which could eventually prevent you from noticing issues a regular user would encounter, as observed by Tom Johnson.
“The first rule of usability is to know the user, and also to recognize that you aren’t the user.”
You can overcome this challenge by asking coworkers or external testers to go through the documentation with a fresh pair of eyes.
Remember to do testing early enough before publishing because you may need several rounds of reviews and changes.
You can start the testing phase by executing all direct instructions. The testers should flag all bugs or problems with the sequence of actions they notice.
Still, functional instructions aren’t the only prerequisite for usable technical documentation.
All other parts of the documentation need to work, too—you don’t want a broken link to interrupt your users’ reading flow.
While it’s safer to check the internal links manually, you could save time and automate the inspection of external links. Sphinx, a Python documentation generator, has a built-in link check builder you could use for that.
Lastly, once you’re done with technical aspects, don’t forget to review the documentation for the flow of information. Disorganized thoughts can’t help your readers even if they’re factually correct.
For this part of the testing, you should ask external testers for input.
They aren’t familiar with your internal processes, so their impartiality allows you to see how the users who haven’t seen your product before will interact with your technical documentation.
And that’s it for testing!
This step may seem less demanding compared to the other parts of the technical writing process, but it’s essential for ensuring an excellent user experience for your readers.
Step 5: Publish the Docs
Finally, the world gets to see the documentation your team has worked so hard to prepare.
Your choice of authoring tools can make or break the documentation experience for you, so make sure you choose the right one.
We’ve come a long way from the beginning of technical documentation.
When Geoffrey Chaucer first devised the astrolabe in the 1390s, he wrote the user manual for the device on paper.
Unlike Chaucer’s readers, yours probably expect clickable documentation, available online.
You can choose between three common solutions:
- Creating the documentation website
- Publishing docs on GitHub
- Using a publishing tool
Designing a website requires an amount of work disproportionate to the benefits you’d get. GitHub, on the other hand, comes with limitations in the design and structure.
Therefore, your safest bet is to use an authoring tool with built-in publishing capabilities.
Archbee is an excellent choice here because it allows you to publish the docs from the same place where you’ve written them.
This option means that you don’t have to worry about formatting going wrong, as frequently happens when you copy and paste text and images from one platform to another.
Additionally, using Archbee will centralize the entire technical documentation process.
You could use the same tool starting from recording notes you make during the research phase, during writing, editing, and all the way to publishing.
If you want to see some examples of technical documentation powered by Archbee, check out how our clients customize the platform to fit their needs.
So, approaching the selection of technical writing tools with consideration can help you streamline the authoring process from start to finish.
You should also keep in mind that clicking the publish button doesn’t mean your technical documentation is completely done.
The following section discusses how you can establish an effective documentation maintenance plan to keep your docs evergreen.
Step 6: Establish a Document Maintenance Plan
Since you’ll probably update your product over time, you also have to maintain the documentation so that it reflects the changes.
Only an up-to-date knowledge base can be a valuable resource for the readers trying to understand the product, so you have to establish a document maintenance plan you can follow to keep updating an effortless activity.
The first thing your plan should cover is who is responsible for the maintenance.
Is it the dev who changes the source code, or should the technical writer scrutinize the product for alterations and update the documentation as changes are made?
Either way, the person tasked with maintaining the docs should know it’s their assignment. Archbee’s document verification feature can help you with this.
You can select a subject matter expert from your team, and Archbee will periodically notify them to verify the accuracy of the document.
Source: Archbee on Youtube
Next, your maintenance plan should define how you communicate the updates to the readers.
While some companies don’t find it beneficial for users to indicate changes, others—chiefly the software ones—flag the alterations.
Here’s how MicroStrategy does that in the What’s New section of their REST API documentation.
Apple goes a step further in the API documentation maintenance and categorizes the changes into modifications, additions, and deprecations, as you can see in the image below.
Whether you decide to announce the updates or not, it’s important to always maintain your documentation and keep it usable.
Maintenance may be a perpetual work in progress, but if it provides your readers with accurate documentation, the time you spend updating the docs will be worth it.
Conclusion
As you can see, writing technical documentation doesn’t have to be a chore. A bit of research and planning will go a long way in helping you present your product coherently.
Still, document creation is as smooth as you make it, so make sure you select the most appropriate tools for each step in the process.
We hope we’ve managed to answer all the questions you might have had about how to write technical documentation: step-by-step process, and we wish you many well-written updates in the future.
