Great engineers are highly sought after in today’s job market.
Technical writers are also increasingly in demand.
That’s not surprising, given that both need to possess specific and complex skills. And you know what’s even rarer?
An engineer who knows how to write great technical documentation.
Besides being very valuable to any organization, engineers who know how to write well get better with each project they work on.
Having that skill is a win for all sides—that’s why in this article, we’ll provide you with some excellent tips on how to hone it.
Read More
If you want to write good technical content, you should develop a feel for it. That might sound abstract, but you can do it by consuming the type of content you aim to write.
As an engineer, you undoubtedly know that certain input produces a certain output. In other words, if you write good code, the result is a working feature.
The same is with technical content—the input is what you read, and the output will be the documentation you write.
As Lana Brindley, Documentation Manager at Timely, pointed out on Quora, there’s something to learn from anything you read.
In short, when you read quality content, it helps you to internalize good practices and improve your own writing.
So, what should you read? Brindley recommends “anything you can get your hands on”, but let’s narrow that down.
Blogs can be an excellent resource for actionable information about the process of technical writing.
For example, I’d Rather Be Writing is a blog by Tom Johnson, a Senior Technical Writer at Google.
He writes about trends in the industry, offers advice about technical writing, and has detailed guides on various topics like API documentation.
Another good resource is the TechWhirl blog.
It has articles on improving technical writing skills, tips and tricks, beginner guides, etc.
Those two blogs are just the tip of the iceberg of content on technical writing you can find on the internet.
It’s helpful to have some way of saving articles and guides you come across for later, as well as organizing them by topic or source.
You can do that and much more with Raindrop, a handy tool for managing bookmarks.
That way, you can ensure that nothing valuable will get lost and deprive you of reading well-written content.
Of course, blogs are just one source where you can find that. Picking up a book is a great way to learn from trusted experts, and there’s literature specifically for engineers interested in writing.
One is A Scientific Approach to Writing for Engineers and Scientistsby Robert E. Berger, which focuses on improving writing skills.
Whether you take a deep dive into technical writing guides on blogs or immerse yourself in books, the important part is to—read.
The more you read, the more naturally the right words will come to you, and the better writer you’ll be.
Start With an Outline
To write a quality piece of technical documentation, it isn’t enough just to sit in front of a blank page and start pouring words on it.
You should have a basic structure and a plan of what your document will look like.
An outline is like a sketch of a final product. It helps you organize your ideas and the key points you want to cover.
Also, according to David McMurrey, a technical writing expert, it’s useful for demonstrating accountability to the person overseeing your work.
Therefore, you shouldn’t take creating an outline lightly.
It’s a vital part of planning a document, and some writing experts like Mary Cullen advise that you invest half of your time on that part of a task.
Although it is important, an outline doesn’t have to contain every detail that will end up in your document—it’s here to provide you with a reference when you start writing.
McMurrey proposes starting with a rough outline with major headings and specific topics to gather information on.
In the example below, you can see he writes the topics for every chapter in the form of a question.
Answering the questions next to the headlines will encourage you to look more into each topic and develop a more formal, specific outline as you research.
There are certain tools that can help you do that.
For instance, a mind mapping tool can be useful while brainstorming the structure and topics for your document.
The one you can see above is made in Coggle, an online mind-mapping software you can use in your browser.
Our own product, Archbee, can also simplify creating an outline for your documentation with its ready-made templates.
It offers templates for different types of technical documentation, like tech specifications, project proposals, monthly sales recaps, etc.
By using those templates, you can save time and simplify the process of creating an outline.
Even with the most basic of outlines, you can do yourself a big favor in facilitating the writing process.
The structure and the plan you get that way can be invaluable to the quality of your content.
Adapt the Language to Your Audience
As an engineer, you have expert-level knowledge of your field.
However, in technical writing, you often need to put yourself in the shoes of others who don’t if you want to communicate that knowledge successfully.
That can be challenging because you’re most likely surrounded by other engineers in your day-to-day work, and it’s easy to forget that a wider audience doesn’t have a grasp of the terminology you use.
But, it’s crucial to adapt if you want to be an excellent technical writer, as Tom DuPuis advises.
Therefore, it’s vital that the audience your technical writing is aimed at understands it, whether it’s a user guide for a home appliance or API documentation intended for software developers.
How to achieve that?
One of the most effective ways is to use plain language, which is simple, straightforward, and avoids inflated vocabulary and convoluted sentences, instead focusing on the message.
For example, take a look at the example of legal language below—that is also a form of technical writing.
As Bradley Nice, Content Manager at ClickHelp, points out, the first two paragraphs don’t hold any valuable information for the reader.
Furthermore, the language is full of legal jargon, and the long sentences make the text difficult to read.
Using plain language can make a significant difference:
As you can see, the text above is shorter and easier to read while still preserving the information for the reader.
Some types of technical documentation don’t fulfill their purpose if you don’t write them in plain language.
For instance, what would be the point of a user guide full of terms a buyer of a product can’t understand? Below, you can see an example of a well-written manual.
Even if someone glanced at it right now and didn’t know what it is for, they can undoubtedly understand the instructions and its simple language.
On the other hand, if you write documentation for developers, you should adapt to them and their knowledge. Therefore, some use of industry jargon is inevitable.
Will the non-developer understand sentences like the one underlined above? The answer is no. But, they’re not the audience for this type of documentation.
Software developers are, and they’ll certainly understand it.
One of the reasons they will be able to do so is also because the example above is well-formatted. Let’s dive into what that means in the next section.
Focus On Good Formatting
As we mentioned in the previous section, alongside adapting language, good formatting is crucial for making technical writing accessible to readers.
Formatting is essentially how you design your document.
And that's important for readers because they don't go to technical documentation for reading pleasure—they go to it to find some information they need.
So, good formatting makes that easier for them. If you don't know where to start, you can check out one of many excellent technical writing style guides out there, like the IBM Style Guide.
More than 400 pages cover all the conventions that technical writers might need, including formatting.
For instance, you can find the rules about formatting unordered lists, where they recommend how to arrange them and offer an example of a list:
In addition to using bulleted and numbered lists, there are several more elements of formatting you should consider using in your technical writing:
- Headlines
- Subheadlines
- Short paragraphs
- Visual elements
What does that look like in practice? Let's take a look at an example from one technical report.
As you can see on those two pages, the author used headings and subheadings to structure the information in the document.
There are also two bulleted lists and a diagram for a prototype the document is about.
Paragraphs could be shorter, but they still aren't walls of text that are hard to read.
However, the way the document looks is only one aspect of the formatting—you should also pay attention to how you structure information.
To make it easier for the reader to digest information, you can arrange information from the most important to the least.
In this inverted pyramid structure, the crucial information for the reader is on the top. Then the supporting details come, and the last is information that is good to know but isn't essential.
Pathfix, one of the companies which use Archbee for their documentation needs, arranged their document about workspace that way.
First, they deliver the most important information—what a workspace is and how to access it. Without knowing that, you can't start using that feature.
After that, there's less important but still useful details about how to invite other users if you're working on a team project.
Lastly, information about restrictions is good to know but isn't essential.
If you pay attention to formatting your technical documentation, it will be easy for your readers to read it, use it, and find what they're looking for.
And that means it’s fulfilled its purpose.
Support Your Writing With Graphics
As you can see in examples of technical documentation we used in previous sections, the writers often use visuals along with the text.
There are good reasons to do so. First, it's a part of good formatting practice—visuals break up the text, making it easier to read.
Also, even more important for technical writing, they support the text by illustrating crucial information and concepts, so it's easier to understand.
Take a look at the example below—which description is easier to process, graphic or textual?
The same principle applies to technical documentation.
As Kesi Parker, a technical writing influencer, puts it, visual elements make technical writing more efficient.
For some types of technical writing, graphics are more than only an aid—they're essential.
If you need proof, imagine a user manual for a physical product that doesn't have any visuals. For example, what would the page from a manual of this Sony camera look like?
With so many parts and instructions, it would be very challenging for a technical writer to describe it so the customer can understand it—especially because the first-time camera might not be familiar with the terms like "viewfinder."
You can use a variety of visuals in your technical writing like:
- Diagrams
- Tables
- Screenshots
- Photographs
- Charts (pie charts, bar charts, progress rings…)
The important thing to keep in mind is that they should support your writing.
For example, here's how we used pie charts in one of the articles from our blog.
As you can see, the visual illustrates the argument in the text above it, thus making it easier for a reader to understand and retain.
The charts in the example above are made with Canva, an online graphic design tool packed with different options for creating supporting visual elements.
For instance, if you're looking for graph templates, there are 1,787 of them available—and you can design your own, too.
To sum up, using graphics in your writing is a great way to convey complex information.
Find a way to implement them effectively, and you'll raise your documentation to the next level.
Make Sure You Review the Documentation
After you’ve written your technical documentation, don’t just release it to the world immediately. Before that, you should take a step back and review it.
This phase has multiple purposes—to check for grammar and proper language use, verify the information’s accuracy, and see if the documentation is helpful to users.
For the first part, you can use tools to assist you. One of the most well-known is Grammarly.
Grammarly checks for grammatical errors, punctuation, and spelling and gives suggestions regarding phrases, wording, and sentence structure.
It’s a useful tool without a doubt; however, according to Veronica Stork, Programmer Writer at Sitecore, you shouldn’t blindly follow it.
Tools like that aren’t made specifically for technical writing, so they can suggest words that aren’t suitable for the technical writing style.
“So before you accept that synonym for “function,” take a moment and remember that while useful, automatic writing assistants are still not as smart as you are.”
When you finish your self-review, why not get a second opinion from someone on your team?
If you use Archbee for your technical documentation, anyone from the team can collaborate on a document, as well as leave you comments and helpful feedback.
That way, your teammates can offer a fresh perspective and let you know if there are any inconsistencies, errors, or some parts that need additional clarification.
As Erin Grace, User Education Manager at Apptio, points out:
“There’s no computer program that can yet accurately tell the writer whether they’ve described the functionality correctly, or if their explanation will make sense to the user group at which the docs are aimed.”
And why stop with the reviewing process? As we mentioned, it’s important to assess if the document will be helpful for the intended users.
That’s why you should consider giving it to them before release.
With Archbee, you can give permissions to anyone you want to get feedback from.
By engaging users, you get valuable feedback—who can better tell you if the documentation is well-written than those you wrote it for?
In conclusion, going through the whole reviewing process like that ensures that your technical writing is polished and ready to be released.
Conclusion
The engineer’s knowledge can be even more valuable if they know how to transfer it to others—and that’s what technical writing is for.
Whether you write for your peers or a general audience, writing technical documentation will be easier if you follow our tips.
By reading more quality content, preparing an outline for documentation, adapting your language, focusing on formatting, using graphics, and reviewing your writing, you can become such a combination of engineer and writer that is rare to find.
