Best Practices for Creating Technical Documentation

The uncomfortable truth of technical writing is that everyone can write, but not everyone can write well.

In this article, we’re bringing you six best practices for creating technical documentation that are sure to make documents more helpful and accurate, and the writing process more time-efficient than ever.

Let’s dive right in and see how technical writing pros make their documentation shine!

Don’t Assume Prior Knowledge

Technical documentation should always help readers understand complex concepts, and not add to their confusion.

This seems like a simple rule to follow, but it’s actually what a lot of documentation gets wrong.

That’s because technical writers (or whoever is writing the documentation) assume prior knowledge and don’t take the time to explain their subject so that even someone new to the product can understand it.

Consider this example from Reddit.

This inexperienced programmer is having trouble understanding the documentation for Pygame, a set of Python modules designed for writing video games:

There are some very important points to note here. First off, the person writing the documentation has failed in their mission to onboard a new user to Pygame.

Secondly, we can discern that the problem was that the documentation wasn’t written with a new user in mind, but rather for more experienced programmers, meaning an important audience was shut out from using Pygame to write their games.

Finally, as you can see in that last line, the consequence is that this user is now thinking about learning other programming languages because the documentation just seems like an insurmountable challenge.

This really is the worst-case scenario.

The lesson here is that technical writers need to become master over-explainers to ensure their documentation actually helps people (even newbies, like our Redditor above.)

Mike Pope, a technical writer with 30 years of experience in the field sums it up nicely:

We've been known to tell a developer "If it isn't documented, it doesn't exist." Not only does it have to be doc'd, but it has to be explained and taught, and demonstrated. Do that, and people will be excited -- not about your documentation, but about your product.

To build on that, James Bennett, a software developer, provides some tips on how to write documentation that leaves no room for confusion. Among other things he advises writers to:

• Provide overviews in each document so that users don’t get lost and are able to find what they need in as little time as possible.
• Include use cases and examples for users to see the product in action.
• Document even the code itself because, in his own words, “The greatest library in the world would fail if the only way to learn it was reading the code.”

One final tip we can share is to also collect feedback for your documentation and let users tell you if it has helped them achieve their goals.

Many documentation sites do this very effectively by simply adding a micro-survey at the end of each document, like this:

In short, don’t be afraid to over-explain with your documentation.

Some users might gloss over the parts they already know, but your new users and beginners will definitely appreciate your efforts.

Collaborate With Technical SMEs

Quality technical documentation is never a one-man show.

Technical writers do their best work when they have access to subject matter experts (SMEs) who supply their knowledge to ensure that everything that ends up in the document is accurate and up-to-date.

And it’s not just the developers who should be included in the documentation process. Research has shown that top companies insist on making technical documentation collaborative.

Here are some other experts that are often involved:

Along with helping writers understand the ins and outs of the product, other contributors can help you go above and beyond with documentation.

For example, service and support staff can point to some aspects users often struggle with.

Marketing and sales staff can help writers make the product more attractive to potential customers.

Let’s look to another technical writer to see how closely writers should collaborate with SMEs:

As you can see from this enthusiastic answer, the collaboration between technical writers and SMEs should be continuous for best results.

Writers work best when they know where they can direct their questions and don’t need to wait around long for answers.

This collaboration can start even with the research phase of writing a document.

Carrie Miller, an expert technical writer, even recommends spending time in scrum meetings and getting immersed in the product as much as possible:

After the document draft is finished, it should also pass a round of reviews to make sure all the information is accurate and actually helpful to the user.

For example, GitLab’s technical writing workflow includes reviews from other technical writers on the team, as well as product designers to guarantee a perfect end result.

It might seem quite difficult to organize so many eyes on one document, but it doesn’t have to be.

Modern documentation software, like Archbee, offers plenty of collaboration features, such as inline comments, tagging, and version history.

Remember, collaboration with SMEs is crucial for success in creating technical documentation.

Writers carry an awesome responsibility in creating a document, but they shouldn’t be the only source of knowledge in the text.

Add Code to Your Technical Docs When You Can

When creating technical documentation designed to make developers’, programmers’, and IT professionals’ jobs easier, a really helpful practice to follow is to supplement documentation with live code.

This goes for both internal development teams and IT professionals on the client’s side.

For example, software development works much better if the code and documentation are created side by side.

Documenting code can help existing developers remember what each line of code does and why it was written.

This is particularly useful in long-term projects when it becomes difficult to track the code.

Equally important, explaining the code can help with onboarding new developers as the team grows.

If new developers have access to notes and comments made at the time the code was developed, they can start working almost immediately, without needing someone to guide them.

In the following example, you can see how code can be added to documentation to explain the usage, parameters, and expected result:

On the other end of the spectrum, code snippets and examples can be added to documentation to help programmers on the client’s side integrate a product into the company’s systems and use it to full potential.

Let’s look at a great example from GoCardless. This short guide shows the user how to create a billing request. It starts with an overview of the goals and requirements for the action:

Next, we encounter a description of the process:

Finally, the document is supplemented with an API reference the user can simply copy and paste to run the action:

Notice that there are several programming languages to choose from and there’s even a handy copy icon to easily copy the entire snippet of code.

Can you see the value in this?

The programmer tasked with implementing the GoCardless system can work a lot faster by using the code in the document and there’s no fear of them getting confused.

That’s because the document does a great job describing the action and even providing useful information, such as the time and skill level needed to complete the task.

This is exactly why adding code to documentation is so helpful for developers, no matter what side of the product they’re on.

It makes their job a lot easier and speeds up task completion, resulting in more efficient work processes.

Add a Quick-Start Option

On the subject of speed and efficiency, there’s another great practice you can implement in your documentation to achieve both: a quick-start option.

Remember how we said that over-explaining might cause more experienced users to skip parts of your documentation?

Well, quick-start guides are designed for exactly that segment of your audience.

They’re added to documentation to enable users who know what they’re doing to install and start using the product in as little time as possible.

If that’s a little unclear, let’s illustrate it with a familiar example.

Imagine you just bought a washing machine. You are no stranger to washing machines and you know how they’re used because you’ve seen them in action a million times.

So once you have yours, all you really need is a quick guide on how to do your first load.

Once you’ve got it up and running, the full documentation will still be there when you’re ready to learn more advanced options or encounter a problem that needs fixing.

The same principle can be applied to even the most complex software product. So here’s a more specific example.

GitHub has a great quick-start guide that lets developers dive straight into the API, without having to read too much introductory text.

Instead, they teach a user how to use their rest API with common use cases.

These use cases include things like pulling up bits of information and requesting user profiles.

The documentation user simply needs to copy the code into their command prompt to get the desired result.

GitHub uses an excellent tactic here. They’re making the user learn by doing, instead of reading textual instructions. As you can imagine, this makes for a much more engaging user experience.

Moreover, quick-start guides also help with knowledge retention.

That’s because they employ experimental learning techniques which are proven to be superior to more classical studying methods, such as reading.

In fact, studies have shown that practicing instead of reading can actually double the amount of information retained over time.

To sum up, quick-start guides enable users to install and start using a product in as little time as possible.

They not only provide a more engaging user experience but may also help the lessons in the documentation really stick.

Including them in technical documentation is a great practice that’s well worth the effort.

Keep Documentation Consistent

In a previous section, we determined that quality technical documentation should help users understand the product, and not add to their confusion.

An important step towards achieving this goal is to keep your documentation consistent throughout your library or knowledge base.

You already know this instinctively, but it’s worth pointing out that not being consistent with aspects like naming practices, formats, and even tone of voice can make people unsure of what they’re reading and even start to doubt the quality of documentation.

So, how can you achieve consistency with your documentation?

The best practice is to build a style guide that will be applied to all future documents.

Here’s Google’s documentation style guide, just to show you a pristine example:

This guide outlines everything from the preferred tone of voice to formatting practices for every document.

It even has a dictionary that shows writers which versions of commonly used words are preferred.

This might seem overly pedantic, but it’s actually quite important.

For example, imagine you employed a team of technical writers all of whom use the phrase “username”, except for one that prefers “account name.”

In that situation, users might get confused and not realise the two terms actually mean the same thing.

Consistency can also mean employing certain UX practices across all documentation to help users navigate the documentation and learn how to use it quickly and efficiently.

Here’s an example from Microsoft’s documentation guide. This section outlines some principles for making content more scannable for easier use:

As you can see, Microsoft recommends breaking up text with headings, lists, quotes, and so on.

But for this kind of advice to work, it needs to be applied consistently throughout the documentation.

Readers will grow accustomed to having a table of contents and headings in the documents, so confronting them with a stray document that’s a wall of text is a good way to ensure the document won’t be read.

There are many more elements to making documentation consistent, so don’t hesitate to model your own rules and guidelines after existing guides, such as Google’s and Microsoft’s.

Just click on the links we provided under the examples above and start setting some good rules to make your documentation more consistent.

Have a Repeatable Process for Creating Your Documentation

As products (software or otherwise) become more complex, there’s a growing need for ever more documentation.

This is good news for aspiring technical writers who stand to see more opportunities in the field.

In fact, the employment of technical writers is projected to grow faster than the average for all occupations.

However, this also means that technical writing processes need to become more efficient to accommodate this growing demand for documentation.

In practical terms, this translates to making the writing process repeatable by establishing technical documentation workflows.

You can do this by breaking the writing process down into a few steps that need to be taken in order for a quality technical document to be created in as little time as possible.

Let’s see how a technical writing pro does this. Amruta Ranade is the Head of Docs at Airbyte, an open-source data integration platform. This is her technical writing workflow:

On the left-hand side, you can see the four main steps to creating a technical document:

• Research and planning
• Creating a draft
• Editing
• Publishing the final draft

This is pretty standard stuff and we recommend following these steps in your own workflow.

These key parts of the process are then broken down into smaller steps to make them more manageable.

For a more detailed overview of this process, you can check out our article on the technical writing process once you’re done with this one.

Another practice that will help you establish a repeatable process is using templates.

If you write your documents according to the same set of instructions each time, you’ll not only speed up the process but also boost the consistency of your documentation because all document types will be structured in a similar way.

And as we’ve said before, consistency is a key ingredient in providing a comfortable and trustworthy user experience.

This is another aspect quality documentation software can help you with.

Specifically, our own documentation software, Archbee, allows users to easily create and save document templates for all kinds of documents.

It even comes with a set of ready-made templates for a variety of use cases. For instance, here’s our template for tech specification:

Having a solid workflow and relying on quality templates are two good practices to follow if you want to make the technical writing process repeatable.

Integrate them into your process and create technical documentation more efficiently and faster than ever.

Conclusion

We hope this list of best practices for creating technical documentation will help you on your way to making your writing process more efficient than ever.

Our last piece of advice is to always use quality documentation software for your technical writing needs. We designed Archbee with all of these best practices in mind.

It has features that will help you ensure your documents are useful to readers, let you collaborate on documents, include code snippets and quick-start menus, and keep your documentation process consistent and repeatable.

But don’t take us at our word. Sign up for our free trial and find out for yourself.

‍

FAQ