What is Technical Writing and How to Become a Technical Writer
The Complete Software Developer’s Technical Writing Guide
A blog is a useful piece for many reasons not only to you but to other software developers in tech.
Technical writing helps a software developer to share their technical knowledge/experiences with other software developers in software engineering.
Technical writing is a writing discipline that involves communicating complex information to those who need it to carry out a certain task or achieve a certain goal. Because of this, technical writing is often defined as “simplifying the complex.”
It also boosts your understanding of the topic you're writing about and shows your technical expertise clearly.
The most unique thing about technical writing is not only you have been able to generate excellent future opportunities (a remote job in tech, a freelance writing contract or a guest post opportunity at a big tech company website etc), but it can help you build an online presence which eventually helps you in your career being a software developer.
Sometimes, I do go back and read my blog posts when seeking information on a specific topic.
Also If you like helping others learn, enjoy being part of open-source projects and showing others how to join in, or find satisfaction in explaining complex ideas in easy-to-understand ways through your writing, then technical writing is a great fit for you.
In this article, I aim to explain how programming and writing can merge to elevate our developer skills. Yes, writing! I genuinely think we all possess some level of writing ability. I'm here to provide you with writing tips, advice, and examples to help you become a more proficient developer and communicator.
What is Technical Writing
Technical writing is all about giving clear and detailed instructions to help users, fellow developers or managers to help them understand a technical product or a technical skill or idea.
A technical writer is someone who creates these tutorials and technical documentation.
Technical writing could be:
How to user guides or integration between two technical SaaS
Online support articles
Technical Reports that present information on a specific topic, often after conducting research or experiments. They are common in scientific and engineering fields.
Technical Proposals, These documents outline a plan, idea, or project clearly and persuasively. They are used to seek approval, funding, or collaboration.
Internal metamaterials for programmers and API documentation for developers.
In essence, a technical writer conveys technical details in a manner that allows the reader to effectively apply that information for a specific purpose.
If you are starting in technical writing and trying to write about software development/programming or what you’ve learned in tech, but haven’t written your first blog yet, you’ll find the largest amount of value in the first two sections of this blog post where I talk about how to get started as a technical writer or blogger and how to scale your blog.
The rest of the blog you’ll find useful to fill in any knowledge gaps you’ll need to succeed as a software developer writer and thrive in the workplace and advance your career.
“If you have a dream, you can spend a lifetime studying, planning and getting ready for it. What you should be doing is getting started.”
—Drew Houston
Writing is Everywhere?
The top two online resources people use to learn to code are technical documentation and Stack Overflow, with blogs rounding out the top three.
The trifecta of enabling people to teach themselves about technology includes clear documentation, a vibrant community offering solutions, and frequent posts.
Developers value a wide range of additional sources, including how-to videos, written tutorials, books, and forums-- they put together the sources and formats that suit their learning style the best.
Being able to express your ideas clearly within the team and online is a valuable skill, as many developers find it challenging. Just think about how much writing you do every day that doesn't involve writing code. This skill is a superpower.
You engage in various forms of writing like Slack chats, emails, internal developer docs, RCA drafts, readme, code comments, Git commit messages, pull requests, code review comments, annual performance feedback, meeting notes, and more.
Mastering writing is crucial for software developers. Inadequate writing skills can impede their career advancement beyond a certain point. Many engineers come to realize later in their careers that "soft skills matter just as much as code."
Why Writing is Crucial for Developers
JavaScript, TypeScript, PHP, Go, Java — there are so many different programming languages out there and you may even be fluent in many of them.
As we strive to produce higher-quality code in our tech careers, the ability to write and communicate effectively in everyday language becomes a crucial skill, one that may be underestimated in the field of software engineering.
Software engineering is not just about code. It’s about people + code.
How engineers articulate their thoughts about the code can be just as critical as the code itself. Regardless of your stance on this matter, we can unanimously acknowledge that our words have the power to either enhance or hinder the effectiveness of the code.
Writing can help you increase your luck surface area.
L = D * T, where L is luck, D is doing and T is telling.
- Jason C. Roberts
6 Major Benefits of Technical Writing
It helps you understand concepts on a deeper level.
You need to research the concepts you’re explaining, which exposes you to different ideas, applications and gotchas.
The concepts sticker better in your brain when you explain them to others.
By structuring and presenting information for others, you often uncover gaps in your knowledge. As a result, it also helps you progress faster in your dev career.
Technical writers are lifelong learners because with each new technical blog, you research and write, you will become an expert on that subject.
Writing also fosters a deeper understanding of user empathy. It prompts you to focus more on the perspectives and feelings of the readers or product users, rather than solely relying on your viewpoint.
Here are some additional benefits:
Furthermore, you can generate income as a technical writer by contributing to various organizations. Check out these Awesome-Companies-Who-Pays-Technical-Writers.
In College, I Studied by Tutoring Others in a Hostel
Explaining something, or even pretending to, forces you to organize your knowledge coherently, exposing gaps in your knowledge and reinforcing the parts you do know.
The best way to learn is to teach and Writing is a great asset for every developer.
Instead of just paying attention, people and businesses reciprocate it to you. When you write a technical blog post, you receive instant feedback. Your technical writing also aids in spreading the word, opening doors to even more intriguing opportunities.
There's also a lucrative career to be had in technical writing if you find you like it and Pretty much everything I write on my blog these days is concepts I'm trying to get a better understanding of. If I can't explain it in writing, I don't have a proper grasp of it.
What are the Examples of Technical Writing?
As a technical writer, your role involves translating intricate technical information into accessible and user-friendly language. Technical writing encompasses various forms, including creating step-by-step tutorials and comprehensive guides.
The primary goal is to facilitate understanding of any technical aspects of a product or service, whether among internal team members or end-users.
With that in mind, the following examples of technical writing should provide you with a clear understanding.
This is a very simple example of supertokens review and how it is why "supertokens" is good user authentication.
This is a very good example of how you can build a tutorial along with building an app. In this blog, I've shared a step-by-step guide to build an e-commerce store by Medusa which is an open source alternative to Shopify.
In this guide, I shared how you can deploy LLMs with MindDB and OpenAI
A complete tutorial on how you can migrate your database from Supabase to HarperDB
5- Product Documentation
The product documentation includes instructions on effectively using and integrating with other developer tools.
Writing a product documents requires good technical writing skills and organizational knowledge. These are just a couple of examples that come under technical writing.
and technical writing requires high levels of skill in research, visualization, and the ability to connect with a wide variety of audiences.
Tip- "Ask yourself, 'Does the title capture the reader's interest?' If it does, they'll likely delve into the introduction and then decide, 'Is it worth investing my time in this entire piece?' One prevalent mistake I often observe in technical posts is an excess of introduction or, conversely, too little.
A precisely crafted paragraph can effectively set the stage for a technical blog post.
How do I Start as a Technical Writer
By far, the most common question I get about "Technical Writing or Blogging" is about how to get started.
In life, it seems the biggest obstacle to doing something and becoming what you want to become is getting started.
Whether it’s starting a new workout regimen, training for a marathon, starting a business, writing a book, or—more specifically, in this case—writing, the most difficult part is always getting started.
It’s easy—and tempting—to waste countless hours debating what you should do.
It’s much easier to "read", "read" and "study" than to start "writing".
But, the secret is, you only need to take one step at a time.
and look around most developers in software engineering aren’t writing code 24/7 most of us spend plenty of time doing other things every day.
That includes:
Demoing a new functionality across the team within a company or customers.
Documenting a new or an old feature in your product.
Updating a JIRA ticket-related.
Creating backlog work to support that new feature.
Of course, there’s always time for bathroom/lunch breaks and scrolling Twitter too 😉
so don't overthink- just start
"Writing is like learning to play basketball."
- David Perell
To be a successful writer and find opportunities, you must have 3 skills.
Coding
Writing
English
Yes, Before you even begin writing, you must first understand English, including its tenses, spellings, and basic grammar.
Your readers do not want to read an article that is riddled with grammatical errors and poor word choices.
In the tech industry, English has become the de facto language for communication among software developers, engineers, and other tech professionals worldwide. It is the language used for documentation, programming languages, and tools used for development.
Learn to Communicate Ideas Simply and Clearly
Knowing how to implement a technical feature does not necessarily imply that you can explain the process to others.
Being a good teacher requires empathy and the skill to convey information in a manner suitable for your target audience
You don't understand something if you can't explain it to a six-year-old.
Einstein, Albert
There isn't a flawless strategy for becoming an exceptional writer. You might wonder, then, why I'm discussing this topic. It's because it's crucial to address this right from the beginning.
“Don’t look for a strategy; look for your unique voice in writing and build your style."
The only writing hack you should know.
Less tech is more, I work with React 90% of the time.
If you’re writing for the first time, give yourself more time to figure it out.
Allow yourself to write poorly.
Stop preparing and start acting.
To understand your audience, ask these questions before you start writing.
Who are your readers?
What do they search for on Google or what problem they are facing?
Which blogs they are reading currently?
How will they be reading?
How To Come Up With Blog Post Ideas
Write the article that would have prevented you from spending hours Googling and scratching your head.
Whenever you learn something new, write about how you learned it and what you learned.
Write a story about your field, interest, or profession.
Select a blog post from your favorite blogger that you found enjoyable and explore the same topic from a fresh perspective, or tackle a different subject from a similar angle.
Note- If you did something interesting in your software engineering career but you're keeping it to yourself, you're missing out on a big opportunity generator.
The internet is best navigated through writing when it comes to promoting your ideas effectively.
Conclusion
Writing is a low-hanging fruit for most skilled developers.
The reason every developer should write a blog post about what they learn in software engineering is that writing makes them discover that perhaps they don’t understand something as well as they thought they did.
Teaching and writing about anything is the best way to learn about it, and it's a low-hanging fruit for you to start a new lifestyle because you already have firsthand experience, so all you have to do is show up, write a 12 blog post this year and evaluate the outcomes, and plan your next move!
“Read to collect the dots, write to connect them.”— David Perell
The bottom line is that honing your writing skills and putting in a little extra effort in your writing can genuinely enhance your abilities as a developer. You might find these tips useful for collaborating with other developers, maintaining your work, creating your content when needed, or even drafting project proposals, among other tasks.
Technical Writing Resources
Advice for Technical Writing (A well-written blog post by Chris from CSS Tricks)
Technical-Writing-Resources (A GitHub repo by Cynthia Peter)