Becoming A Software Technical Writer

Who is a technical writer?

Using some products is very straightforward. Either because the product itself is not complicated or the task it's meant to complete does not require much knowledge. For example, figuring out how a toothbrush works.

There are however certain products that have many moving parts or are used for tasks that require prior knowledge and even specialization. An example of such a complex product is a car.

A mechanic is usually a specialist who understands cars enough to fix them. The manufacturers of these cars sometimes need to pass on information about their cars to mechanics either by capturing them in schematics or written manuals.

Who from the manufacturer's team should create these manuals? I am sure you already figured out where am going with this, yes it's someone with the title of a technical writer.

This individual needs to not only understand cars well enough but also should be good at communicating or passing on this knowledge to those who need it. Hence the combination of Technical and Writer.

Who is a software technical writer?

Borrowing from my car analogy, we can then say the technical component here is software.

You are classified as a technical writer if your written content requires some level of technical knowledge to create or understand.

In this post, we will primarily discuss how to become a software technical writer.

Who should consider a career in technical writing?

Maybe you just stumbled on this blog post or you have been searching around to see if technical writing is a good career choice. Here are some reasons or conditions that might sway you in either direction.

Wanting to make more money as a writer

There are different types of writing out there, UX writing, content writing, copywriting, etc. Unless you are an established writer, the compensation for most writing jobs especially freelance positions are based on word count. This makes it very difficult for most writers to make more without having to work extra hours. This is not the case for technical writing. Given the fact that you need a combination of some technical and writing skills, tech writers are highly sorted after and the compensation comes close to what most software engineers earn. Even in the world of freelance, you can secure writing gigs that pay 100s of dollars per piece without the stress of having to write a certain amount of words.

A software engineer experiencing burnout

The first thought of many people is that engineers make more than most people. But the truth is you don't have to be an engineer to make a lot of money.

Tech as an industry is where the money is at and everyone in it is making more than their counterparts in other industries. So at the end of the day, it's about the value you bring to that company, If a company struggles to find someone with good enough tech skills who can write and you come along (Its a real struggle by the way), then your bargaining powers go way up.

Tech writing is good for software engineers who are constantly stressed by crunch time and work and life balance. They can carry their tech knowledge and use it in a tech writing career, where code doesn't break and you can move at a much more relaxed pace. You have the job of educating people to use software products. You can build demos and write code snippets using your tech skills to further improve what you share.

Becoming a software developer down the line

If you can jump on the path of becoming a software engineer right away do it. If you can't or are not sure if it's for you, becoming a technical writer is a good first start for many reasons.

You will work a lot with software engineers and get a feel of the job to figure out if it's something for you. Also, most of what you learn as a technical writer can be carried over to software development.

Transitioning into a software development role is also easy since you will already be working for a software company and can make the transition without needing to switch companies.

Some benefits of being a technical writer?

Compensation

The compensation for even entry-level technical writers is up there with most software development roles and can easily go up within a short period. This can be a huge boost for a general writer making the jump.

Side income

Unlike many roles in software development as a writer, you don't have to go out bidding or constantly chasing gigs to make a side income. Many software companies have technical writing programs that pay technical writers to produce or submit technical articles. Most of which pays in the 100s of dollars. You can find the list of programs and how much they pay on Who Pays Technical Writers [↗].

Remote work

As you may know, by now most tech workers can work remotely and technical writers are no exception. Most companies are open to remote work and this especially benefits someone who might have a hard time finding technical writing jobs in their area.

Solid career trajectory

The option to take your career to new heights and direction is endless. You can transition into roles such as software development. You can move up the technical writer role to positions such as a senior editor. You can also switch industries, maintaining the writing part of it and moving into new industries such as legal, health, or manufacturing. This may however require getting abreast with the technical side of that industry or getting certified.

Growing number of jobs

I will say this again there are many technical writing jobs out there and many companies making those positions remote further widen the pool. You can check LinkedIn, Write The Docs [↗], and Content Writing Jobs [↗] to get a feel of the job market.

Do I need to know how to code to be a technical writer?

Yes, and No, You see to get code to work you need to know exactly what to type out and the possible side effects of your work among other things. A technical writer's job is to be able to interpret what has been created and how to use it for the end user. Will knowing how to code help you better describe the product sure! But you can also err on the side of the user and pretend to not know much about the product and make it your goal to understand as much of it then write it out for others to follow.

With that being said, there are some basics of software development and product usage that you need to know, just like your potential readers. The basic skills you need to acquire typically depend on the type of product you will document.

For API products you need to know how to make an API [→] call using a tool like Postman [→] and the Open API spec [↗] for documenting them. For user interface-based documentation you need to be able to use the product from the interface and be able to guide users to do the same.

There are other general tools and processes you need to get familiar with as well such as using Markdown [→] instead of Word to craft your content and the Doc As Code [↗] publishing workflow.

Skills required to become a technical writer

In the section above I hinted a bit regarding what you need to know to become a technical writer. In this section, I will lay out a few of the must-haves to becoming a technical writer.

General software knowledge

Programming language: Knowing at least one programming language can be useful, mostly when you want to test out products created by software teams in other to better document them. I would say getting acquainted with Javascript [↗] is a good start as it can be used on both the frontend and backend side (NodeJS [↗] of the software. This makes it possible for you to test out different types of products. Also getting familiar with HTML and CSS will help. As far as how to learn it goes you just need to know how to create simple scripts to do basic things like calculate stuff and if you can how to make API calls. You can get started with a very good site like W3 Schools [↗].
Reading code: Most of the code you will present to end users are usually created by the dev team and so at best you need to be able to read and understand them and this is something you can get better at by asking your Subject matter expert questions as well as a healthy dose of Googling.
APIs: Most software products these days are sold or exposed as APIs. Application Programming Interfaces(APIs) allow other software teams to integrate software products created by others by calling on exposed URLs and passing data to and from the software systems. For example, Amazon calls on delivery company APIs to let you know the status of your delivery by a third-party company. Check out this article [↗] to learn more.
Setting up software: Since most of your readers will be going over the documentation to understand how to get a piece of software up and running or integrate them into their software, it goes a long way to practice how to do this yourself by following documentation written by others to get a feel of what information to present to your readers when you create your documentation.
Version Control: If you have ever used the Google docs version history [↗] feature then you have experienced version control. In the world of technical writing, you will use a tool like Git [↗] to handle this. Git allows you to mark the progress of your documents and revert if you need to. It also plays a role when it comes to collaborating with others. I will suggest going on Youtube [↗] to learn more about it, as it's best to learn it visually.

Authoring process

Markdown: Markdown is a writing format that allows you to format your written documents ie: bolden, italics, create tables, bullet points, etc, just like in a word document. The difference being the content you create is not tied to any one tool. HTML is what is used to represent content structure on the web and since Markdown is a subset of that it's easier to convert your written content to HTML to be rendered on the web. I will recommend searching on Youtube [↗] to learn how to use Markdown. It's easier that way.
Open API Spec: As mentioned in the previous section, APIs have become a popular means through which software companies deliver their software to customers. This needs to be documented and one good way to do that is by using the Open API spec. You can learn more about the Open API spec from its website [↗]
Docs As Code: The whole idea of Docs As Code is to handle the documentation workflow just as developers handle code. Which includes contribution, review, testing, and deployment workflows. The good news is different companies have different versions of this and mostly forgivable if you are not familiar with this approach before joining.
HTTP client: Am going to talk about APIs again. To be able to organize and even collaborate over API development and testing, an HTTP client will come in handy. One popular HTTP client is Postman [→] which comes with features such as collections that allow software teams to share with you everything you need to test out an API.

Grammar improvement tools: Let's talk about writing for a bit. Since you will be writing in a human language there are chances you will make errors or will have the need to improve your written text. That's when tools likeGrammarly [↗] comes in handy to help with grammar and spelling errors. You can also use tools like Word tune [↗] to help rephrase sentences to switch things up a bit.
Code Editors: Getting acquainted with a Code editor like Visual Studio Code [↗] is very useful. With an editor, you get different parts of your text or code samples highlighted in different colors that help identify different parts of your work, something you don't get with plain text editors like notepad. Code editors also come with a plugin system that allows you to install other useful tools like spell checkers and to run Git directly within the editor.
Command line: This one is not a must but helps improve your productivity. You can create files and folders using your computer's Folder explorer but with the terminal, you can create a whole bunch of files/folders quickly. Also as you get better in say Shell or Javascript you can write scripts to automate a lot of stuff because there are a lot of command-line tools that make your life a lot easier.

Working within a team

Project management tools: On big teams you will be working with stakeholders and other technical writers. Usually, in such teams, writing projects are undertaken in sprints [↗], and tools like Jira [↗] are used for managing the progress of work. Depending on the company you might be doing work based on an Agile [↗] workflow. You don't need to go out of your way to learn all this before landing a job, however, it might be worth watching a video or two on the subject as this could help during your interviews.
Subject Matter Expert(SME): A subject matter expert is likely your closest contact person or persons in your tech writing job. This person knows and provides a lot of information regarding a product you are documenting. This can also be a group of people and sometimes changes when you move on to document other products.
Understanding the Org Chart: Another good thing to know is who does what within your company, organization, or immediate team. This way you know who to go to for what when you need extra info that the SME can't provide it. For example, you might need information on how much traffic your software product can handle, an SME might be able to provide this info, but a better person might be someone from the devops [↗] team.
SEO? maybe: Most companies need technical writers to just put out information for their customers. However, in some roles, you might find yourself writing tutorials or general technical articles that are meant to attract potential customers hence the need to write content that captures the right keywords needed to get it optimized for search engines.

What if English is not my mother tongue?

If you are like me where English is not your native language, you might be questioning if technical writing or writing, in general, is something you can do. Well, the truth is many of your readers will also come from non-native English-speaking countries. And so the content will have to be prepared in plain English.

You can depend on tools mentioned in the Grammar improvement tools [→] section to help improve your writing.

You should also certainly be involved in a review process to get your peers to look over your work and suggest improvements. This compounds over time towards improving your overall writing skills.

How do I find a job?

First, you should spend some time learning the tools of the trade and the landscape. Once you are ready you can perform a test run by writing for publications such as the Freecodecamp [↗] and also getting some paid writing gigs.

Once you are ready you can use any of the platforms mentioned in the growing number of jobs [→] section to find a job.

What do the job interviews look like?

The interviews are mostly focused on testing your technical comprehension and general writing skills.

You might be assigned a writing task as part of the interviewing process but unlike software development tasks that take a couple of days to a week to complete, most writing interview tasks involve a take-home assignment crafting short documentation for a segment of a software product and occasionally suggesting or improving existing documentation.

This was a long article but I hope it was at least useful 😅.

Here is another article you might like 😊 How to make a markdown link open in another tab

Tech Jobs | Newsletter [↗] 🗯️ Got a question? 🔗 Share on 𝕏

EDDYMENS