paint-brush
Software Developers, Why Haven't You Started Technical Writing Yet?by@theankurtyagi
1,128 reads
1,128 reads

Software Developers, Why Haven't You Started Technical Writing Yet?

by Ankur TyagiOctober 20th, 2023
Read on Terminal Reader
Read this story w/o Javascript

Too Long; Didn't Read

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.

People Mentioned

Mention Thumbnail
featured image - Software Developers, Why Haven't You Started Technical Writing Yet?
Ankur Tyagi HackerNoon profile picture


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.


If you did something interesting in your software engineering career but you're keeping it to yourself, you're missing out on a big generator of opportunity.

Start writing and it’s an effective way to promote your ideas on the internet.

“Write the blog you wish you found when… https://t.co/PcXR0fL9QF

— Ankur💻🎧💪 (@TheAnkurTyagi) October 3, 2023


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.


stackoverflow-developer-survey-2023-technical-writing


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.”


Youngsters: Your software engineering career will significantly improve and you’ll get better future opportunities in tech if you start writing for 30 minutes each day and post 2-3 blogs online each month, but very few developers are actually able to do this over the long term. https://t.co/damIJ5gXys

— Ankur💻🎧💪 (@TheAnkurTyagi) October 4, 2023


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.


technical writing


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 I Become a Better Writer as a Software Engineer


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.


How Writing Can Boost Your Software Career


Writing can help you increase your luck surface area.


how to 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-Pay-Technical-Writers.



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.



inbound cold email


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.


  1. SuperTokens Review– an Open Source Alternative to Auth0, Firebase Auth, and AWS Cognito.

This is a very simple example of supertokens review and how it is why “supertokens” is good user authentication.


SuperTokens-Open Source-User-Authentication-review


  1. How to Use Medusa to Create Next.js E-commerce Store

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.


Medusa alternative to Shopify


  1. How to Deploy LLMs with MindsDB and OpenAI

In this guide, I shared how you can deploy LLMs with MindDB and OpenAI


How to deploy LLMs


  1. How to Migrate Your Database From Supabase to HarperDB

A complete tutorial on how you can migrate your database from Supabase to HarperDB


Technical-writing-examples-Supabase-to-HarperDB-migration


5- Product Documentation

The product documentation includes instructions on effectively using and integrating with other developer tools.


supabase-integrations


Writing a product documents requires good technical writing skills and organizational knowledge. These are just a couple of examples that come under technical writing which require 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.


The worst enemy is “self-doubt.” pic.twitter.com/fw1691QRSY

— Ankur💻🎧💪 (@TheAnkurTyagi) August 10, 2023


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.


Build at least one compounding asset in ur software engineering career



– Start a blog– Start a newsletter– Start recording YT videos– Start a podcast– Start building networks

Build, Publish & Repeat

Future opportunities are waiting for u on the internet

Cc @TheAnkurTyagi

— Kap.ts (@Kaperskyguru) February 17, 2023


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



David Parell- Writing is like learning to play basketball


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.


Gergely Orosz Tweet


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.


How to Become a Standout Writer in the AI Era:

Before writing your next blog post, ask ChatGPT to write one on the topic and show you what generic things are already available on the internet so you can avoid saying that and write what's important and unique to the audience.

— Ankur💻🎧💪 (@TheAnkurTyagi) February 16, 2023


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.


Write the blog post you wish you had found when you googled something.

— Ankur💻🎧💪 (@TheAnkurTyagi) March 20, 2023


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.

There is a sweet spot for writing technical posts and tutorials. Write for the professional who hasn't had time to learn that thing yet, and link it back to things they already know. For example explaining a modern JS technique to someone who knows jQuery.

— Rachel Andrew (@rachelandrew) February 20, 2019


Conclusion

Writing is a low-hanging fruit for most skilled developers.


If you think you can learn a lot in tech from reading a blog post; try writing one this week.

— Ankur💻🎧💪 (@TheAnkurTyagi) October 2, 2023


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


Also published here.