Why Should Developers Know How To Write Technical Content

Dragos
Dragos
Founder, robot with feelings. From planet Aiur.

This article discusses why developers should know how to write technical content. It also provides some resources that developers can use to learn how to write technical content.

đź“š Table of contents

Looking for a documentation platform that's easy to use?

Try Archbee for free. Capture complete product knowledge from across your company and publish it with fully customizable portals.

Here’s a statement that’s by no means groundbreaking, but it’s true—developers love to write code.

That’s understandable, since writing code allows you to build amazing software, solve problems, be creative, learn and improve. And we only scratched the surface with this list.

However, developers should also practice a different kind of writing—technical writing.

Creating technical content can bring many benefits to developers. In this article, we’ll discuss what those are and try to inspire you to start writing technical content.

To Create Better Documentation

Technical writers stand in the middle between the software developers who created the product and its users.

They need to learn as much as possible about a product or service to pass that on clearly to the end users.

But sometimes, circumstances arise when developers need to step into technical writers’ shoes and create technical documentation—and that’s why they should know how to do it.

You can look at it this way—who can know more about the software than the developer who made it? This Quora user below sums it up neatly.

Source: Quora

If, like Rich Cohen says above, “the developer is the only choice” for creating detailed and usable documentation, then it’s essential they’re skilled in it.

Luckily, most developers don’t shy away from writing tasks.

According to a survey conducted by Tom Johnson on his technical writing blog I’d Rather Be Writing, 82% of developers wrote at least some of the documentation for the products they built.

Source: Archbee

That survey provided another interesting statistic—as Johnson points out, six out of ten respondents think that technical writers should switch to editing and publishing highly technical content like software documentation, rather than actually writing it.

Why? Because, as some of them think, technical writers don’t necessarily have enough knowledge and technical skills, while developers and engineers do.

But, as we mentioned, developers should know how to write technical content primarily in order to create better documentation.

There are plenty of resources available where they can learn how to do that—for example, Google’s Technical Writing Course aimed at developers and engineers.

Source: developers.google

And when developers learn how to write technical content, they can create excellent documentation, be it user-friendly basic manuals or complex developer docs for their peers.

For instance, they can create documentation like Docker’s, a platform for building, running, managing, and distributing applications.

They have very helpful features in their docs, like internal links that lead the user to more information, cheat sheets, and recaps at the end of some sections.

Source: docs.docker

A very skilled technical writer who isn’t a developer can also write and structure complex documentation like that.

However, a developer instinctively knows what information is relevant, what could use more explanation, and where readers might stumble.

Why? Because they build software every day and know it inside out.

To Improve Their Problem Solving Skills

Developers solve problems on a daily basis. Their job includes using advanced skills to deal with issues in designing, coding, debugging, and, essentially, every other part of a software development process.

And in a complex process like software development, things can go wrong at any moment—if a problem persists, that means wasted time, resources, and, ultimately, unhappy users.

That’s why it’s not surprising that employers rate problem-solving skills very high when choosing the right developer to hire.

For instance, take a look at how problem-solving skills compare to other core competencies employers look for, according to HackerRank’s 2018 Developer Skills Report.

Source: hackerrank

That’s right—they’re at the very top, higher than even programming language proficiency or other technical skills.

Therefore, improving problem-solving skills should be among the priorities for any developer. But how does writing technical content contribute to improving them?

According to Duncan Anderson, co-founder of the education company Edrolo and a former Senior Associate at Google, writing encourages developers to think in a way that facilitates easier problem-solving.

Source: Archbee

As he explains, by writing, you extract thoughts and ideas, break issues down to their components and start thinking about them differently.

Breaking problems down into more manageable issues is a method many technical writing experts and programmers recommend.

For example, V. Anton Spraul, computer scientist and author, thinks it’s essential.

Source: Archbee

Luckily, writing technical content can be an excellent way to brush up on that skill.

Let’s look at Apple’s developer documentation.

They have many sections about solving various problems, like the one about diagnosing memory, thread, and crash issues.

Source: developer.apple

They take the approach of breaking down those instructions into smaller steps.

So, for instance, in the subsection about locating memory corruption issues in your code, they explain what tool to use, how to enable it, which flags to use from the command line, and how the tool works.

Source: developer.apple

If a developer wants to write technical documentation like that, they’ll need to think about the problem and what is the best and most efficient way to solve it.

Also, not only will they reinforce their knowledge about the topic they write, but problem-solving will become more and more ingrained in their skillset.

To Refine Their Communication Skills

What does a typical working day look like for a developer? As you probably know, being a developer yourself, an image of a person coding all day at their desk doesn’t represent reality well.

Developers usually have a plethora of daily activities that don’t involve writing code, like meetings, debugging, reviewing code, etc.

The data from the Mac Git Survey 2021 illustrates that well. As you can see below, most developers spend only about half of their time at work coding.

Source: git-tower

That frees up time for other tasks, and many of them include communication.

Contrary to the mentioned outdated image of a developer tucked away at their desk writing code all day, they spend much of their time communicating with people inside and outside of their organization.

A developer who goes by Eluda explains it like this:

“Most of the things we typically do involve communicating with people like your team, colleagues, clients, users, and other developers.”

Therefore, with communication being a significant part of a developer’s day-to-day work, you should improve your communication skills as much as possible.

And writing technical content is an excellent way to do that.

After all, writing is a form of communication. According to Tanaka Mutakwa, Software Engineering Team Lead at Hotjar, writing technical content is a great exercise in refining those skills.

Source: Archbee

The more you hone your writing skills, as Mutakwa suggests, the better you’ll be at presenting your technical knowledge to any audience, from laymen to other developers.

That could be especially important while writing technical content for non-expert readers.

If your communication is too technical, they could become frustrated with your content, as this programmer on Twitter suggests.

Source: Twitter

Simply put, if the readers don’t understand your content, that defeats the purpose of creating it.

A company that seems to really understand that is Twilio. They provide programmable communication tools, and the audience for their documentation is expected to have considerable technical knowledge.

However, that doesn’t mean that they can instinctively know how Twilio works, and the company is aware of that, so they communicate with users in an approachable and laid-back manner.

Source: Twilio

Your goal as a developer writing technical content should be precisely that—to know how to communicate something effectively to your audience.

And, like any other skill, the more you brush up on it, the better you’ll use it.

Related: Best Practices in Code Documentation for Software Engineers

To Develop Teaching Skills

One of the reasons developers should write technical content is to improve their teaching skills. What does one have to do with the other? Let’s examine that.

First, teaching skills can be very beneficial for developers because it’s common practice in tech companies that more experienced developers onboard new hires—in other words, show them the ropes.

For example, Zapier has an elaborate onboarding program that includes getting junior developers acquainted with every aspect of the company, from their colleagues to the tools and the knowledge they’ll need in their work.

Although Zapier’s onboarding is mainly remote, their senior and junior developers still occasionally meet up face-to-face to learn together and strengthen their bonds.

Source: Zapier

Teaching skills are essential for situations like these at Zapier.

If you know how to pass on your knowledge to your teammates, the whole organization can improve. Why? Because you can make others better at their jobs, leading to high-quality results. It’s a chain reaction of benefits.

Luckily, employees usually love having mentors. According to LinkedIn’s survey cited on CNBC, learning opportunities can directly affect how long employees stay at the company.

Source: Archbee

Something that companies like Zapier have is excellent technical documentation that provides their employees with plenty of opportunities to learn.

Writing that documentation is a great way for you as a developer to improve your teaching skills—you already have the knowledge, now it’s only a matter of understanding how to pass it on.

If you work with documentation platforms like Archbee, that process can be even more productive.

In addition to dozens of features for creating and maintaining technical documentation, Archbee also has helpful collaboration features that can aid you in your teaching.

For instance, when you write a technical document, you can leave comments, tag your teammates and instruct them inside the file.

Source: Archbee

That way, you can also get feedback from others in the organization about your writing, which you can then use to improve it further.

And the more you improve your writing, the easier teaching will be—whether teaching other developers about the advanced aspects of a product or a service or teaching people from other departments about the basics they need to know.

To Further Their Career Through Writing

Writing technical content can result in many benefits for a developer, as we already discussed. But there is one more that we shouldn’t overlook—furthering their career.

You would be hard-pressed to find a tech company that doesn’t want to find and keep top-notch software developers who can build them a winning product.

Of course, those developers would need to have impeccable technical skills. However, while they are rare, developers who are also skilled at writing can be even more valuable to a company.

As Lem Diaz, Head of People at Upbound, points out, companies look for developers with a broad skill set.

Source: Archbee

And writing technical content is a skill that’s increasingly sought after in the business world.

For example, according to the U.S. Bureau of Labor Statistics, the need for technical writers will steadily increase in the coming years.

When it comes to the software industry, it’s projected that it will rise by nearly 4% by 2031.

Source: Archbee

The need for developers who can also write great technical documentation is already apparent if you look at job listings for software developers.

For example, many companies list advanced writing skills as a requirement in their job ads, like General Motors.

Source: Indeed

So, although they need a software engineer, an ideal candidate should have more than just technical skills.

Therefore, knowing your way around writing technical content can undoubtedly open up more opportunities for you in the job market.

But how can you show off your writing skills to potential employers? After all, even if you’re writing, for instance, internal technical documentation for your company, you can’t publish that to the world.

One of the ways to do that is to create your own blog.

That’s what Artturi Jalli, who’s also a developer, did.

Source: codingem

As he says, he started writing for Medium, and his success there encouraged him to create Codingem, a blog and learning platform.

The exposure Jalli had on Medium and Codingem created new career opportunities for him.

If you invest your time and effort into learning how to write technical content, you can see the same results.

Conclusion

We hope that we’ve shown you why taking up writing technical content would be a wise decision.

Improving your technical writing skills can only make you a better developer overall.

It allows you to constantly refresh your knowledge, look at problems from different perspectives, learn how to communicate and teach better, open up more career opportunities for yourself, and, of course, create top-notch technical documentation.

In short, technical writing can make you a well-rounded expert. Be sure not to pass up an opportunity like that.

‍

Continue Reading