Let’s say you’ve introduced a new feature and want all your developers to be updated on the addition.
However, it isn't so important that it would require you to explain it to every department right away, but you simply think they should be notified of its existence.
So, how to keep everyone updated without taking them away from their work?
A simple solution is to describe the new feature in the technical documentation well enough that the entire company will understand it, and then send a notification that will let interested parties know where to find more information.
But how do you make sure your technical documentation is suitable for such a wide audience?
That’s what this article is for: to offer tips on writing effective technical documentation everyone will benefit from.
Follow a Documentation Style Guide
Language is fluid, and the rules of its use aren’t set in stone. For instance, in English, linguists have differing opinions on capitalization, spelling, and even commas.
With all these different options, it can be challenging to compose technical documentation according to accepted conventions.
In fact, it’s often unclear what the organization’s accepted conventions are.
This is where a style guide comes in.
Style guides communicate a company’s writing standards and represent a comprehensive record regarding formatting your documents.
For example, if you don’t know whether to use American or British spelling, the style guide will have the answers.
The visual below shows some of the aspects a style guide covers:
These subjects are just the tip of the iceberg. Most style guides also detail countless other facets, such as abbreviations, contractions, punctuation, etc.
For instance, here’s an excerpt from the Google Style Guide:
If your technical writers are unclear on sentence structure, a glance at Google’s style guide will direct them. In other words, this text functions as a reliable, constant writing reference point.
Style guides eliminate trivial doubts such as italicization, bolding, and underlining conventions.
Writers can access definite answers to all their concerns within a few minutes and create beautiful technical documentation.
Structure Your Documentation Well
Let’s say you’re reading about API calls but want to view the authentication information. You revisit the beginning part of the documentation but don’t see it.
Frustrated, you look for the table of contents and can’t find that either.
Such a lack of organization makes it difficult to find information, and wastes the readers’ time. This is why structure is critical—users can quickly locate the information they need.
Matt Wilson, the co-founder of Lift Your Game, has excellent advice on structure:
Always segment your documentation. This creates a clear overview and helps the reader navigate the various documentation articles.
For example, here’s the WSO2 Open Banking Accelerator’s documentation:
The left-hand side outlines every article, clearly indicating the individual texts. With this organization, readers can quickly jump to the sections that interest them.
However, not only is the top-down structure indicated, but so is the individual article structure as well.
Take a look:
The right-hand side outlines each heading so readers know what to expect in this article.
With this structure, they can easily scan the text and quickly determine if the document contains the information they need.
Format Your Documentation for Readability
Although building a logical structure will improve your documentation’s usability, it’s only half the battle.
To truly create high-quality documentation, your texts should be easy to read—in other words, they should have high readability.
Consider this Okta documentation:
The heading is written in bold letters and larger than the remaining text. The reader immediately recognizes this element for what it is: a heading.
In the text itself, important information is highlighted by a thin frame. Furthermore, the most critical term (per-minute) is bolded so readers don’t overlook it.
Finally, all the relevant data is displayed in a table. This layout is excellent, as it creates a clear, accessible overview, and readers can quickly find the information they need.
All these elements make the documentation easily digestible and understandable, contributing to the document’s readability.
An easy method to achieve readability is to utilize a documentation tool, as they often provide Markdown editing—an easy text formatting language.
Here’s how Markdown works in Archbee:
There’s no need for lengthy HTML syntax. Instead, you can format the text however you please, with just a few keystrokes.
Hyperlinks, heading formatting, and even code formatting are all done instantaneously, and you can easily optimize your documentation for readability.
Write for the Entry Level
You never know who’s going to read your documentation. It might be an experienced senior developer, but it could be a junior developer just beginning his career.
You want your documentation to be accessible to everyone. As such, it’s a good idea to write for the entry-level reader and include explanations and descriptions.
After all, a knowledgeable audience can always skip these explanations. However, if you exclude them, the entry-level reader will need help understanding the documentation.
Canva’s documentation handles this aspect very well:
The article begins with the definition of a data provider, educating readers on the document’s primary terms.
Furthermore, the document also includes a terminology section, which further explains any unfamiliar phrases.
With this resource, even a complete newcomer should understand the documentation.
In the same vein, also pay attention to acronyms. Although you know what API, HTTP, and SSO mean, there’s no guarantee everyone will.
As such, try following the advice of John C. Friedly, an MIT lecturer:
Don’t just name-drop acronyms, but explain each abbreviation. You don’t have to write out the entire phrase every time, but one definition will mean a lot to your more junior audience.
Write Using Plain Language
You’ve probably heard of KISS: a popular programming acronym that stands for the maxim keep it simple, stupid.
Essentially, what it means is that developers shouldn’t needlessly complicate their code. Although intricate code might seem impressive, a simple approach is often more effective.
The same principle can be applied to technical documentation.
You might want to demonstrate your API knowledge, documenting each HTTP method, defining the request parameters, and listing possible endpoints.
However, how many readers will understand that language?
A recent survey revealed that documentation could be clearer for developers.
Look at the numbers:
Almost all developers consider confusing documentation a considerable problem and have clearly frequently come across such inadequate documentation.
Therefore, to make developers’ lives easier, writing using plain language is essential.
Avoid technical jargon, steer clear of long sentences, and your documentation will be much more accessible.
For example, look at this Smartlook article:
This document discusses iframe elements, both same-origin, and cross-origin.
However, instead of expecting the reader to understand these terms, the article takes the time to explain each phrase in plain language.
With these clear descriptions, even a non-technical audience should understand same-origin iframes and be able to utilize the documentation.
Address Your Audience Directly
The primary purpose of technical documentation is to make your software product more accessible for your users.
Consequently, the focus should be on the reader. You want to elucidate how the software will help them and what benefits they’ll gain.
The easiest way to create this emphasis is to address your audience directly.
By utilizing the second-person singular (you), you can make the readers feel like the texts were written especially for them. The tone will be much more personal.
Consider these two sentences:
Which is more helpful? Which makes you feel like a priority? The example with direct language, of course.
Most companies nowadays employ such you phrasing precisely for this reason, as it helps make the documentation more relatable to the reader.
Just look at Stripe:
The entire article is written in the second-person singular, creating the illusion that the article was written especially for the reader.
Furthermore, Stripe also uses possessive pronouns. In the first step of the Add funds process, the document could have said: determine how much you want to add to the balance.
However, Stripe swapped out this the for your. With this word choice, they’re directly addressing their audience as much as possible.
Add Plenty of Visuals
Sometimes, it’s easier to explain concepts with visuals than with words.
Let’s say you want to disclose how to change the privacy settings. To do so verbally, you’d have to expound on where to navigate and what buttons to click, describing everything in detail.
However, by using images, you’d simply have to upload a screenshot or two.
Visuals are incredibly effective at conveying information; one image is often enough to explain complex processes.
Consequently, it’s worth including screenshots in your technical documentation, as readers should understand the content more quickly.
For example, here’s how ActiveCampaign’s documentation uses visuals:
The article explains how to create an app in so many words, then attaches an image showcasing the exact steps that need to be taken.
This screenshot helps readers navigate the app creation process, walking them through each necessary action.
Such visuals are proven to facilitate learning and information retention. Look at these findings:
Readers are more efficient at processing information when it’s expressed visually.
The dynamic nature of screenshots (as opposed to static text) is simply much more engaging than the written word.
As such, try to include as many visuals as possible—your readers will thank you for it.
Provide Enough Examples
Visuals aren’t the only elements that can elevate your technical documentation.
When explaining technical concepts, you’d do well to provide some examples, as they go a long way toward helping developers understand the inner workings of the software.
Think about it—developers chiefly work with code. They spend their days hunkered down in their IDE and tend to think of software from a technical perspective.
Therefore, when explaining such technical concepts, it’s a good idea to include code snippets.
These samples should help developers better understand the documentation, as it speaks their language.
For instance, look at this Pipedrive article:
Instead of just explaining the success responses, Pipedrive illustrated what the success response looks like.
With this code snippet, developers will immediately recognize a success response when they see it.
In the same vein, it’s also constructive to include sample values. By providing actual possible values, developers will have an easier time when setting up your software.
Here’s how Yoast’s documentation handles this:
Yoast has listed some sample values, illustrating exactly how developers can configure their website’s metadata.
With these examples, readers will realize how much control they have and, ultimately, better understand Yoast’s capabilities.
Put Your Documentation to the Test
As mentioned, the main reason for writing documentation is to help customers use your software. Your readers should have a pleasant user experience.
However, the first prerequisite for this goal is usable documentation. Without user-friendly texts, your readers will struggle to understand your software.
As such, it’s imperative to test your documentation’s usability, and there are a few ways of doing so.
One approach is paraphrase testing: an exercise where users read the documentation and then repeat its content in their own words.
Writing experts Caroline Jarrett and Janice ‘Ginny’ Redish are a fan of this method:
With paraphrase testing, you’ll learn if the way you communicate was clear enough; if you explained concepts well enough.
Furthermore, watch out for anything misdescribed—that’s your sign to revise your text.
Besides paraphrase testing, it’s also worth conducting plus-minus testing. Here’s the methodology:
After the people doing the testing note their pluses and minuses, they’re asked to elaborate on their thought process.
This is a highly comprehensive approach, as users can give feedback on every documentation component.
Whichever assessment you choose, you’ll have a reliable, effective method of testing your document’s usability.
Review the Technical Documentation
While usability testing essentially functions as a user-side review, you should also conduct an internal documentation review.
End-users can easily evaluate the document’s user-friendliness, but they can’t judge its technical accuracy.
If you rely on usability testing alone, you risk publishing incorrect information.
This is why you must engage your colleagues (a senior employee or an SME) to review your document. That way, a fresh pair of eyes can verify everything.
Toward this end, it’s worth devising a review schedule.
Here’s an example:
With such a record, someone will always be assigned as the document reviewer, and you’ll have a reliable, consistent review plan.
In addition to an accuracy review, also ensure to review the grammar—you don’t want to publish documentation with any punctuation or spelling mistakes.
Luckily, there are plenty of online tools to help you out with this. For example, Grammarly is a popular resource that stays on top of your document’s—you guessed it—grammar.
Here’s the tool in action:
The solution highlights any sentences that can be improved, immediately offering an alternative.
With this tool, you’ll never have to worry about reviewing your grammar; the app will do it for you.
Conclusion
Technical documentation is an invaluable part of software development. It enables developers to share knowledge, helps end-users adopt your product, and provides stakeholders with an inside look at the technicalities.
However, the documentation must be well-written to reap all these benefits. If these texts are poorly composed, they’re not much good to anyone.
Therefore, don’t write your documentation in a rush. Instead, take your time; structure it well, add visuals. Do your best to create a beautiful, effective technical document.
Believe us—it will pay off, and you’ll soon wonder how you ever worked without technical documentation. Follow out tips for writing effective technical documentation and your team will love you.
