Technical Writing for Engineers

Published on Apr 27, 2022 in writing by Veronica Stork
7 minute read

If you are an engineer hoping to improve your technical writing, you’re not alone. Writing is one of the most important “soft” skills you can have. Honing that skill will help you develop a greater understanding of technology, improve developer experience for whatever product you work on, and possibly advance (or change) your career.

Technical writing helps solidify your understanding of a topic. One of the best ways to internalize knowledge is to explain it to others. It forces you to think about why things are done a certain way and address all of the steps necessary to make something work. Once you’ve explained a topic in writing, you will be more confident about your understanding of that topic.

Are you creating a product or working on one? Having great written information about your product helps to improve the developer experience (DX). Accessible documentation, easy-to-follow tutorials, and even descriptive variable names can be the difference between a tool that’s a joy to use and one that makes developers want to throw their laptops across the room. This is why every team should include at least one great technical writer.

If you are that great technical writer, your skill can help you in your career. Being an accomplished developer is impressive, but if you can code and write, that’s extra special. Writing well is crucial if you ever want to move into management, because you will need to be able to translate code for people in non-technical departments.

If you don’t want to go the management route, writing can open up other exciting career paths, like developer relations or technical writing for companies like Draft.dev, which matches tech professionals to their ideal writing assignments.

But even if your career aspiration is simply to be an excellent engineer, writing is important. You are likely communicating every day in writing, whether it be via GitHub pull request, API documentation, or Slack messages to your colleagues. This is even more relevant if you work remotely. Communicating effectively in writing is a crucial skill.

What Makes Technical Writing Difficult?

Some people have the mistaken idea that writing is easy. Everyone writes, after all—on Twitter and Facebook, or in emails and texts. But writing well is an acquired skill, and, like coding, requires practice to get right.

For engineers in particular, it can be difficult to “step back” into a less knowledgeable perspective. Depending on your audience, it is likely that you will need to explain things that seem obvious to you. You may forget to mention steps you do without thinking, like installing dependencies using npm or navigating into the correct folder before starting a server. Skipping steps can spell frustration for your readers, so it is essential to consider this when writing. Technical writing, especially for beginners, often requires you to reset your knowledge of a topic to zero, which is not always an easy task.

Similarly, you may have difficulty understanding your target audience. Are you writing for new developers, senior engineers, or business users who have little to no knowledge of code? What are your readers hoping to take away from your article or tutorial? You must be able to answer these questions before you start writing and keep the answers in mind as you write.

Jargon and acronyms that may be appropriate for one audience will leave another one confused. On the other hand, spending a paragraph explaining what a function is to a senior engineer will ensure they don’t read the rest of your article. And it’s not just about technical know-how. You need to internalize what your audience is looking for when they read your article, then make sure you follow through on giving that to them.

Finally, you may struggle with choosing the right words and structure of your content. In a piece of technical writing, every word you write must be accurate, and every sentence must be correctly placed. You may find yourself agonizing over whether to call something a “function” or a “method” or whether a process should be written in a paragraph or bullet points. Technical writing requires an eagle eye to spot confusing structure or inaccurate wording. You need to take the same care with your writing as you do with your code. It’s just as important.

How to Level up Your Technical Writing Skills

It’s true that writing technical content is difficult, but you can take some concrete steps to improve your skills. Here are some tips that will help you in your technical writing journey.

Read

If you are a software engineer, you are most likely familiar with the concept of “GIGO,” or “Garbage in, garbage out.” This concept applies to writing as well as to computer science. What you put in as a reader influences what you produce as a writer. When you read well-written content, it helps you internalize a good narrative voice. So if all you read these days is tweets, try to switch it up and grab a book.

It doesn’t need to be a book about writing or computers. Read for pleasure! Pick up a novel, a collection of short stories, or some narrative nonfiction. You will find that the more quality writing you read, the more your own writing will improve.

Create an Outline

When coding, it is always a good idea to write pseudocode before doubling back and building your solution using an actual programming language. Similarly, an outline can help tremendously with technical writing.

Writing an article is an iterative process. You must keep coming back and fleshing out your article more and more with each pass-through. The original outline should be basic and cover the general gist of your article. Go through each point of the outline and expand on it with a few bullet points, making sure to include all necessary steps if you are writing a tutorial. Then expand your bullet points into sentences and paragraphs. Each time you circle back, your work will look less like an outline and more like an article.

This method is often helpful when you are feeling writer’s block. If, on one pass-through, you aren’t sure what to put in a section, write yourself a note about what will go there and move on. You can go back later and address your notes.

Keep it Simple

Even when you are writing for advanced readers, it is important to be clear, concise, and direct in your language. Avoid regional slang, unnecessarily big words, and overly complicated sentences. English may be tech’s “universal” language, but remember that your readers are likely to have different cultural and linguistic backgrounds. They will have varying levels of English proficiency, so don’t make it difficult for them.

Use standard English and stick to the topic. Don’t pause your tutorial to tell a joke or craft a complicated metaphor. Just explain your topic clearly. Using a style guide, such as The Chicago Manual of Style, will help you maintain consistency in everything from sentence structure to general formatting.

Another way to ensure clarity is to know when a well-placed GIF, screenshot, or code sample is superior to a written explanation. If you are struggling to come up with the words to describe something, stop and consider if supplementing with a visual example would make it easier for you to explain and for your readers to understand.

Use a Writing Assistant

Tools like Grammarly are extremely useful for catching errors and improving your writing. They can find problems like misplaced or missing commas, run-on sentences, and repeated words. They can also give suggestions on how to make your articles clear, correct, and engaging.

Use common sense when running these tools, however. They are far from perfect, and you need to know when to take their advice and when not to. It is especially important to be vigilant when writing highly technical pieces, because tools like Grammarly aren’t designed to check for technical accuracy. They will sometimes suggest incorrect words or offer synonyms for terms that can’t be reworded. 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.

Just Start!

Establishing a new habit can be intimidating, but don’t let yourself get overwhelmed. You don’t need to start out by writing a ten-part blog series or a 300-page ebook. Start small. Pick a topic you know well and write about it in small bites. Are you an expert on React? Write a tutorial on how to use the useEffect hook. Do you live on the command line? Write a rundown of common terminal commands. Make a blog on Hashnode or Medium and create some content.

Do a little bit of writing every day. It doesn’t need to be a full article—just get some sentences down. In time, writing will become such a regular part of your routine that your day won’t feel complete without it.

Conclusion

In this article, you have learned some techniques for improving your technical writing skills. If this has inspired you and you would like to get paid while you write, consider becoming a technical writer for Draft.dev.

Draft.dev matches technically proficient developers to a huge variety of writing tasks. It’s an incredible opportunity to share and expand your expertise about technologies that interest you while making money doing so. For more information and to apply, head over to our signup page.