In the past few months, I have spoken at events where I was asked 'how do I get started with technical writing?' Most recently, I received over 5 direct messages(DM's) on Twitter asking me how they can get started with technical writing.
This article is the first in this series. I hope you get to understand the fundamentals of technical writing by following through.
Although this article addresses the basics of technical writing, the what, the why, and the how. Subsequent articles will address other questions and lessons I've learned as a technical writer.
So, let's get to it!🤓
What is Technical Writing?
Technical Writing can be referred to as art in form of written documentation that explains a process or a product. This simply means that technical writing goes beyond and above just the software and tech ecosystem because automobile companies need technical writers to document processes, choices, and guides for the designers as well as the users/customers.
This article will be focusing on technical writing in the software development ecosystem.
However, Technical writing in software development is a form of written communication that allows one to write about software tools, technologies, systems, processes, and guides. Mostly with the aim of simplifying complex/unknown terms and processes.
A Technical Writer is a person that writes clear and concise documentation to preserve information, explain complex technical terms or processes.
So, who exactly am I writing for as a technical writer?
As a technical writer, you write for different audiences at different times depending on what the task is about. Understanding what tones, terms, and structure to use is very important. There are two major groups you will be writing for:
Developers: As a technical writer, you write for developers.
- You write internal documentation for a team of developers you work with. This documentation cover tools, APIs, and processes that the engineers on your team are using.
- You create internal wikis and a knowledge base for your engineering team.
- You document
- You write external documentation for developers that will make use of your company's API, tools, or resources.
A technical writer writes documentation for users, this can be customers or users of a product. This documentation can start from 'how-to guides', FAQs, and tutorials.
- As a technical writer, you may need to work with the marketing team to produce marketing and promotional pieces.
Why is technical writing important?
Imagine starting an engineering team for a startup and after a year, two engineers leave the company, you hire new engineers to replace them. But then you have no documents to show how the previous engineers made decisions and nothing to show how to use any API they built. That's scary!
Decisions are made daily, about tools to use, tests to write, APIs to update, Standard Operating Procedures, design systems, and more.
New tools are being built daily. New products are built and released to the market every day. These products come in form of digital and tangible products. People need to be able to use these products and the developers of these products need some sort of guide, manual, or directions on how to make use of these tools, APIs, or resources.
For the developer, they need technical documentation to remind them of why they took certain decisions at certain times. The developers need to reference back to see how they can implement certain tasks, features, research, and the paperwork that was done before the final choice was made.
However, for the users of a service, API, or a tool, there needs to be some sort of manual that directs them on how to use these things to make their own building experience better.
Another group of users is the actual users of a product, be it a washing machine, a mobile application, or a web application. Knowing how to make use of a product for our day-to-day lives is as important.
Although being a technical writer sounds simple, there are a lot of deep tasks and choices to make. Understanding what, when, and how to write a conceptual guide, how-to guide, or clearly, a deep dive into a topic can get confusing. And then writing for the right audience is another thing to figure out.
That's lots of drama, right? But hey! you got this.💪
I am new, How do I get started as a Technical Writer?
Now that you know what technical writing is and why it is important, all you need to do now is to start. The major task for a technical writer is understanding technical terms and explaining them, documenting processes and Tools too.
However, to start out in this journey you need to acquire and build certain skills. This includes and is not restricted to:
Research: To a technical writer, you always have to learn something new. A new technology, a new tool for editing, a new onboarding process, a new tool for creating developer wiki. So, to succeed as a writer, you need to be able to set out time to research.
Ability to consume information and learn fast: As often as you need to research and learn, you need to be able to understand what you research about fast enough to start documenting and writing about it.
Empathy and Audience Perception: This skill is not a must-have, but this skill will make your article pieces standout. This will reflect alot about how you percieve what your readers want. Being able to put yourself in the shoes on your reader just so you are able to offer the kind of solutions they need at the time of reading your article is important.
Technical Skills: You need to be knowlegdeable in tech. Understanding technical terms and knowing when to use a term, concept, or highlight a process is very important. To document an API that's built for a blockchain, it is important you understand what a blockchain is in the first place.
SEO and Analytics: This is the skill that makes you write articles that can be understood by humans and found on the internet by both humans and the cyberbots that serve these articles on search engines.
There are a lot more skills that you need to build on to stay active, but with time, you will figure out those.
Are there any tools I'll need to start writing?
If you're coming from a non-technical background, These platforms allows you to focus on writing instead of worrying about what blogger or Wordpress theme to use to set things up.
Secondly, you will need a spellchecker like Grammarly to help check your tone, grammar, and sentences. Grammarly has a free tier which can be very helpful, However, if you need all the features, then you can get a premium account.
You will need a playground where you dump ideas. As creatives inspiration and ideas can come to you at any time, having a place where you dump all the ideas no matter how stupid is very important. You can use Google docs, Keep, notion, and even a pen and paper can do the magic. All that matters is when you're sitting on that water cistern and an idea pops into your head, you've got somewhere to drop it.
Where do I start from?
Writing! That's where you start from. Create a blog on any of those platforms and start writing.
Just like that?
Yes oh! just like that. You do need to style the blog but, that will be covered in another article in this series.
All you need to do now is pick up your preferred writing materials and start writing.
Ok, what if I don't have a technical background, like I am a content writer that is trying to transition
Oh that! That is not even a problem, all you need is to get acquainted with the tech ecosystem, you will learn more on how to achieve that, but the first thing is to take some introductory courses and read some programming/tech books. I always refer people to 'Computer Programming for kids and other beginners By Warren and Carter Sande' This is one of my favorite programming books.
You can start by reading the book and as you learn new terms and concepts, you can share on your blog by writing about it.
What You Gain as a Technical Writer
As a Technical Writer, you gain a lot because you learn about new technologies and secondly you get to earn! What could be better? More money...
Finally, a career in tech has a lot to do with showing up everyday and like James Clear wrote in his book Atomic Habits, 'when you write everyday, you become a writer'.
Final words? Just start writing!
If you have any requests on articles, please do well to reach out @iamCynthiaPeter on Twitter.