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 five 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 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 the form of written documentation that explains a process or a product. This means that technical writing goes beyond just the software and tech ecosystem because automobile companies need technical writers to document processes, choices, and guides for the designers and the users/customers.
This article will focus 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. Mainly to simplify complex/unknown terms and procedures.
A Technical Writer is a person that writes clear and concise documentation to preserve information and 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 the task. Understanding what tones, terms, and structures to use is very important. There are two significant 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 covers tools, APIs, and processes that the engineers on your team use.
You create internal wikis and a knowledge base for your engineering team.
You write external documentation for developers using your company's API, tools, or resources.
Users/customers
A technical writer writes documentation for users, who can be customers or users of a product. This documentation can start with '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; after a year, two engineers leave the company, and 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 the 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 use these tools, APIs, or resources.
The developer needs technical documentation to remind them why they made certain decisions at certain times. The developers need to refer back to see how they can implement specific tasks, features, Research, and paperwork before making the final choice.
However, for the users of a service, API, or tool, there needs to be a manual that directs them on how to use these things to improve their building experience.
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 use 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 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. But hey! you got this.💪
I am new to technical writing. How do I get started as a Technical Writer?
Now that you know what technical writing is and why it is essential, all you need to do now is to start. The primary task for a technical writer is understanding technical terms and explaining them, documenting processes and Tools too.
However, to start this journey, you must acquire and build specific 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, and a new tool for creating a 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 know, you need 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 stand out. This will reflect a lot on how you perceive what your readers want. It is important to put yourself in your reader's shoes so that you can offer the kind of solutions they need when reading your article.
Technical Skills: You need to be knowledgeable in tech. Understanding technical terms and knowing when to use a word, concept, or highlight a process is very important. To document an API built for a blockchain, you must understand what a blockchain is in the first place.
SEO and Analytics: This skill makes you write articles that can be understood by humans and found on the internet by humans and the cyber bots that serve these articles on search engines.
You need to build on many more skills to stay active, but with time, you will figure out those.
**Are there any tools I'll need to start writing? **
Yes, of course! It would help if you had a blog to publish your articles. There are lots of options to choose from. This blog is built on Hashnode; there is Dev.to, and Medium.
If you're from a non-technical background, These platforms allow 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, you can get a premium account.
You will need a playground where you dump ideas. As creatives, inspiration and ideas can come to you 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?
Writing! That's where you start. Create a blog on any of those platforms and start writing.
Just like that?
Yes, oh! Just like that. You need to style the blog, which another article in this series will cover.
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 them on your blog by writing about them.
What You Gain as a Technical Writer
As a Technical Writer, you gain a lot because you learn about new technologies; secondly, you get to earn! What could be better? More money!
Finally, a tech career has a lot to do with showing up every day, and like James Clear wrote in his book Atomic Habits, ' when you write every day, you become a writer.
Final words? Just start writing!
If you have any requests for articles, please do well to reach out @iamCynthiaPeter on Twitter.