A Brief Introduction to Technical Writing

Image credit: #WOCinTech Chat

Technical writing impacts every developer. They consume content written by technical writers in the form of documentation, and they also produce technical content. Companies and open source projects alike understand that well-written documentation is key to product adoption. In fact, 93% of respondents to a 2017 GitHub survey said that “incomplete or outdated documentation is a pervasive problem” in open source.

So we understand why technical writing matters, but what is technical writing exactly?

In this post, you’ll learn what technical writing is, discover examples of technical writing in software and beyond, and gain an understanding of other skills technical writers develop to create successful and effective documentation.

What is technical writing?

Technical writing is the practice of creating primarily text-based instructional or informational documents for users. In software development, common genres of technical writing include product and API documentation, manpages, tutorials, and guides. But technical writing isn’t limited to software or even the developer tools space; technical writing also includes user manuals for everything from consumer products to manufacturing, aerospace engineering, and medical technology. And in certain contexts, documents like data visualizations, whitepapers, knowledge bases/online help articles are also forms of technical writing. (Technical writing is a specialty of a much wider field of practice known as technical communication.)

How technical writing differs from other forms of writing

Unlike other forms of writing—for example, marketing or ad copywriting—technical writing aims for precision and utility. Think, for example, of a recipe you get in a meal-delivery kit. The recipe lists the exact ingredients you need and the precise measurements for each ingredient. The writing is both precise and concise; recipe writers know that people who are in the middle of cooking a meal don’t want to follow a super long recipe! Technical writers try to convey information in a similar fashion. The writing style is meant to create a frictionless user experience that is almost imperceptible to the reader.

When technical writing is effective, a reader can do more quickly. But when the writing is poor, the reader may have trouble moving forward which can lead to frustration. For example, a developer trying to troubleshoot a problem at work decides to look at the official documentation for a specific package manager. They are in a time crunch and they need to be able to skim the document quickly to find a solution. They’re scanning the page for specific words, phrases, or code snippets that will point them in the right direction. Good technical writing keeps this in mind.

If the troubleshooting steps are vague, incomplete, or full of superfluous language, it will take the developer much longer to accomplish the task. In this scenario, the developer isn’t visiting the docs to admire the writing capabilities of the person who wrote the doc; they’re visiting the docs to help them do something.

Let’s consider an example outside of software. A co-pilot has to refer to a manual in-flight. They need to be able to quickly locate a section in the manual that can help them interpret one of the flight instruments. In this situation, the user (an airplane pilot) cannot afford to spend time pondering what the instructions mean, especially if they’re faced with an emergency. They don’t want jokes or flair, and they don’t want a back story. They want to find the solution to their problem and they don’t want to use more mental energy than they need to.

This is why some technical documents seem “dry” or “lacking in flair” compared to the writing we see in email newsletters, blog posts, or landing pages. While copywriting is used to persuade a user to take a certain action, technical writing exists to support the user and remove barriers to getting something done. Good technical writing is hard because writers must get straight to the point without losing or confusing readers. It requires a familiarity with the subject matter, the ability to listen and observe, and a deep understanding of the reader.

Technical writers can do more than write

In addition to tone, technical writers pay a lot of attention to document design. We don’t read online content the same way we read content in print, so document design is also dependent on document format. Elements of document design include layout, page formatting, typography, color, and other visual aids. Technical writers structure their documents to facilitate reading comprehension. They understand that many readers skim and scan documents in search of the information they need, and writers look for ways to surface relevant and important information to readers. And they also recognize that users need to take steps in a certain order to achieve the desired result.

Technical writing isn’t limited to the act of writing a draft. Technical writers must be familiar with research methods, usability, visual design, and instructional design, among other things. They must know their users and the scenarios that drive users to interact with documentation. They have to be able to search for the right information and know how to ask questions of subject matter experts. They understand how text and visual design work together to create a cohesive user experience. And they review and revise their work as needed, acknowledging the importance of editing in the writing process.

Want to learn more about technical writing?

I compiled a list of technical writing resources for continued learning. It includes style guides, books, online material, and courses.

I learn best in environments where I can learn from experts and apply what I’m learning in the form of a project or an assignment. If that’s true for you as well, I recommend taking a technical communication course through UC San Diego’s Extension program or the Society of Technical Communicators. Other universities based in the United States offer online technical communication courses and certificate programs.

This post originally appeared on my blog.

I'm Stephanie, a Content Strategist and Technical PM. Visit developersguidetocontent.com to learn more about my work!

Sources:

• https://www.collabera.com/find-a-job/career-resources/what-are-the-different-types-of-technical-writing/
• https://instr.iastate.libguides.com/c.php?g=284553&p=1948068
• https://techwhirl.com/what-is-technical-communications/
• https://www.northeastern.edu/graduate/blog/what-is-technical-writing/