A beginner's guide to get started with Technical Writing
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 written documentation that explains a process or a product. This means that technical writing goes beyond 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 you to write about software tools, technologies, systems, processes, and guides. Mainly to simplify complex/unknown terms and procedures.
A Technical Writer is a person who writes clear and concise documentation to preserve information and explain complex technical terms or processes.
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 software developers.
- You write internal documentation for a team of developers you work with. This documentation covers tools, API references, 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, user guides and manuals.
- You might need to work with an API strategy or developer experience team to
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 solutions 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 a guide, manual, or directions on how to use and maintain these tools, APIs, or resources.
The developer needs technical documentation to remind them why they made certain decisions at certain times. They 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. 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, as well as documenting processes and tools.
However, you must acquire and build specific skills to start this journey. This includes and is not restricted to:
- Research: As a technical writer, you must always 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 essential to put yourself in your reader's shoes to offer the 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. To document an API built for a blockchain, you must first understand what a blockchain is.
- SEO and Analytics: This skill allows you to 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 you will figure out those with time.
**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 to 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 a content writer trying to transition?
Oh, that! That is not even a problem. All you need is to get acquainted with the tech ecosystem, and you will learn more about how to achieve that. However, the first thing is to take introductory courses and read 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 earn! What could be better than earning money from a skill?
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 contact @iamCynthiaPeter on Twitter.
