Community Tips

The ABCs of Technical Writing

As developers, we have either had to write or read a technical article or documentation. What do you look for when you write/read an article? Is it the length of the article? Is the balance between theory and examples? In this blog, we will find out what makes a good article and how to write an effective one.

What is Technical Writing?

Before we dive right into tips and tricks for writing an influential article, let us understand what technical writing means and why we need it. To go by definition, technical writing is the practice of conveying complex technical information in a clear, precise, and understandable manner, often to inform, instruct, or guide an audience. Whether you are an individual developer or a professional technical writer, the goal is the same – Education.

Technical Writing Must-Haves

Now that the goal is defined, the next step is to work on actionable points to develop the concept for the article.

Here are some points that we should consider while writing the outline:

  • Clarity: Avoid jargon and overly complex language.
  • Conciseness: Avoid unnecessary filler content and get the information your readers need. Use bullet points, headings, and other formatting techniques to make content scannable.
  • Visual aids: Visuals, such as diagrams, charts, and screenshots, can help clarify complex concepts and make your documentation more engaging.
  • Accuracy: Ensure all technical information is accurate and up-to-date.
  • Consistency: Maintain terminology, formatting, and style consistency throughout your documentation.
  • Organization: Add a logical flow. Organize information in a way that guides the reader through the document effortlessly.

Tips to Write Better

Using the above must-haves, you should write an outline. Once that task is completed, writing the content is next.

Here’s some tips to make your content better:

  • Purposeful writing: Define a specific goal in mind while you start writing
  • Use of simple language: The purpose of a technical article is to explain a concept to the readers; using complex language will only push developers away. 

Things to have in your article:

-Using simple sentence structure  

-Using directives

-Breaking paragraph after every thought

  • Defining your target audience: Defining your target audience helps you decide the level of content. For example, if your target audience is beginners, it is better to write an introductory article with a simple example to follow.
  • Adding frequent checkpoints: To ensure you have your reader’s attention till the end, add checkpoints. For tutorials, you can use screenshots in between, and for leadership blogs, you can use questions/ discussions in between
  • Avoiding too many links: Adding links can help readers with more context, but you should avoid using too many. Instead, have a resources section with all the necessary links.

Using simple examples: Examples that do not require complex setups and are easy to follow


To perfect the article, we should always look up articles or docs that work well and are liked by the developer community.

Here’s a list of my favorite documentation:

  • Vercel: The developer journey in Vercel docs is very well-defined
  • Appwrite: Maintains consistency and caters to all levels of developers.
  • MongoDb: Uses the right amount of visuals and is very concise.


Writing: Software Development’s Underrated Skill

In college, as I was finishing up my engineering degree, I roomed with a bunch of English majors. Every now and then, we’d get together with friends and have short-story writing competitions. Admittedly, not the coolest way to spend a Friday night, but it unlocked my love of writing.

Looking back on my career as a software engineer, manager, and CTO, that time I spent writing was actually one of the most impactful of my college career. Besides helping me as I started, writing contributed to my growth as a developer, leader, and professional.

In this article, I’m going to expand on why writing is such a complementary skill for a software developer and the many ways this skill can benefit your career. I’ll also share some pointers to help you get started as a technical writer and improve your skills.

You Write More Than You Think You Do

“Once somebody hits a minimum threshold of technical skill to hold a job in the industry, about 80% of their ability to succeed in software development is determined by their communication and people skills, not their technical abilities”Ben McCormick, Engineering Manager at Meta

Software development is typically associated with skills like coding, analytical thinking, math, and problem solving. However, equally important is effective communication.

Joel Spolsky, Co-founder of StackOverflow, concurs with this and even goes so far as to say that he wouldn’t hire a programmer unless they can write well:

“The difference between a tolerable programmer and a great programmer is not how many programming languages they know…It’s whether they can communicate their ideas…By writing clear comments and technical specs, they let other programmers understand their code, which means other programmers can use and work with their code instead of rewriting it. Absent this, their code is worthless.”

Spolsky makes a good point, because whether you realize it or not, you’re doing a lot of writing over the course of your day as an engineer. This includes, but isn’t limited to:

  • Commenting on code
  • Collaborating with colleagues and clients on Slack and email
  • Writing bug reports and code reviews
  • Posting and answering questions on community forums
  • Creating technical documentation

Jon Leydens puts it this way in an IEEE article:

“In their first few years on the job, engineers spend roughly 30% of their workday writing, while engineers in middle management write for 50% to 70% of their day; those in senior management reportedly spend over 70% and as much as 95% of their day writing.”

In fact, communication is the primary skill employers are looking for now that remote work is here to stay. By ignoring it, you’re limiting your utility at your current job as well as your future career prospects.

How Writing Can Level Up Your Career

Initially, I mostly wrote for fun and to see if I could get some passive income going on the side. None of my early attempts took off. But they did give me deep insight into the value of technical content as well as lots of practice in creating that kind of content

Come 2020, the pandemic struck and the company I was with at the time hit a rough patch. I was trying to figure out what I wanted to do next and I realized writing full-time was a real option. This led to the founding of

Since then, it’s been a pleasure to see what a difference writing has made, not just for our clients, but also the engineers who write for us, both financially and professionally. Provided you stick with it, writing can help you level up your career too.

  1. Writing Establishes You As a Subject-matter Authority

One of the immutables of life as a developer is that we’re constantly learning. A recent StackOverflow survey found that nearly 75% of developers learn a new technology or framework every few months or once a year. 

Writing is a great way to reinforce your learnings and document your experiments with a new tool. It can help improve your critical thinking abilities and integrate prior knowledge with new concepts. 

What’s more, your observations can help other engineers learn as well. With remote work as prevalent as it is, junior developers don’t get as much face time with their managers and existing use cases and tutorials can help them get up to speed with their work.

Writing can also help you improve your ability to clarify complex topics to non-technical stakeholders and create better alignment between product and business teams. 

In fact, the more you write, the more you build and exert influence, directly accelerating your career trajectory.

  1. Writing Can Help You Find the Job You’ve Always Wanted

Job-hunting in software development can be an aggravating process, especially for newcomers. 

Writing can help you bypass the traditional recruitment system by putting yourself out there. A well-written tutorial is social proof of the fact that you understand a tool or framework well enough to implement it. After all, claiming you know React in your resume is one thing. Publishing a tutorial where you’ve integrated it with other libraries to build a working prototype is another altogether.

Recruiters or engineering managers who spot your work will be tempted to reach out to you directly instead of wading through a hundred other applications. I did the same thing when I was an engineering manager, and others I talked to have confirmed this.

“I once got a full-time offer to join a cloud computing startup as a copywriter on the strength of a few blog posts I’d written,” says Stephanie Morillo, a content strategist and technical program manager. “I was offered a role as a part-time technical writer for an open-source organization, and I even started doing freelance copywriting on the side for [software development] agencies”

Adam DuVander, Founder of EveryDeveloper, goes even further, “I owe my entire career to a couple of articles I wrote…A tutorial I wrote on Webmonkey led to my first developer job. They saw how I discussed the technology and knew before we even chatted that I could handle the work.”

  1. Writing Can Be a Lucrative Side Hustle

Engineering salaries can differ widely based on everything from the language and frameworks you specialize in to where you’re located.

According to StackOverflow’s 2021 Developer Survey, Clojure developers enjoy a median salary of $95,000, compared to PHP developers who make just $38,916.

The average salary for a full stack developer in the U.S. is $101,402 plus yearly cash bonuses of $5,500, whereas it’s around $58,000 for one in Germany and approximately $9,767 for one in India.

Writing can provide supplemental income and help you bridge this pay gap by utilizing existing skills and knowledge., for instance, offers you a chance to do just that. So far, we’ve paid over $600,000 to writers in over 64 countries in the two years we’ve been operating.

  1. Writing Can Lead to Public Speaking and Book Authorship Opportunities

Around 2017, I was writing a lot about using PHP with Docker. While I wasn’t able to monetize the site directly, it did lead to a short, self-published book on the subject that was downloaded by over 1,000 developers. 

It also led to a host of conference speaking opportunities and consultancy offers. I wasn’t necessarily an expert on the subject, but I was one of very few people publishing any material on it and so my work stood out.

James Hickey, Principal Engineer at SAVVY, had a similar experience, “I have had many people reach out to me about doing contract work simply by reading my blog and had many offers to write books in the last couple of years.”

Morillo adds, “I wrote a few articles about tech culture in the mid-2010s and was able to secure conference speaking engagements from them.”

Authorship and speaking also tend to bring you more exposure, which leads to similar opportunities in the future, creating a flywheel for yourself.

Improving Your Skill As a Writer

“I have never considered myself expressive or eloquent, so I used to doubt that I would make a good technical writer…However, the truth is that writing, like every other skill, can be learned and developed through practice.”Linda Ikechukwu, Technical Writer and Developer Advocate at Smallstep

New writers frequently experience the resistance that accompanies all creative endeavors. The only way past this is to have a plan and keep at it. Here are a few tips I’ve found helpful over the years: 

  1. Start With Something Familiar

The first block new writers tend to face is what to write about. It’s easy to get caught up between something that’s easy to write and something that you believe is more interesting for readers. My advice? Go with the former.

Eze Sunday, Software Developer and Technical Writer, echoes this sentiment, “Start writing about the things you currently know and share them with the community. You’ll be surprised how many lives you’ll impact.”

Pick a problem you just solved or a tool you just tried out and write about it, even if it feels like something trivial. Just the act of putting some words to paper can tell you something about your writing style and the unique perspective you have to offer.

  1. Aim for Quality

Quality trumps quantity every time. It’s much better to write a few outstanding articles than to write a bunch of average ones.

Be selective about your topics and go deep when you find one you really like. Some of my most popular blog posts are the ones that delved deep into a subject, like this 4,500-word guide to API development.  

Alternatively, write more often, but keep it short and interesting. David Heinemeier Hansson, creator of Ruby on Rails, Founder of Basecamp, and a prolific writer over the years, used to employ this method a lot (and still does), almost as if he wants to cut short an article before it loses value for the reader. Doing this may also help you get more practice without feeling pressured to write huge articles.

  1. Write Regularly

On the flip side, don’t get so caught up with perfection that you neglect to publish regularly.

Frequent practice keeps your skills sharp and gives you a constant flow of feedback from your readers. Personally, I like to block four to eight hours of focussed writing time on my calendar each week. 

A few other writers I’ve spoken to like to use timeboxes throughout the day to churn out productive content. Choose whatever method works for you, but ensure you’ve set aside some time to write regularly.

  1. Keep Your Goals in Mind

Finally, keep moving towards something. Whether you’re looking to monetize a blog, capture a niche, or just record your own learnings, keep that plan in mind as you work on your articles.

And be honest with yourself. As DuVander points out, “Decide whether it’s a side thing or a main thing. You can make either work, but you’ll want to set your expectations appropriately…There are a lot of ways to use writing in an engineering career.”

Track progress towards your goal with readership metrics. You can do this by creating a newsletter that readers can sign up for, running analytics on your website, and paying attention to comments and feedback.


Many software developers ignore communication skills at their own detriment. I hope some of the data and experiences here offer proof of this, but if you’re afraid to start or don’t think you’re very good, don’t worry. As with anything else, the more you write the better you’ll get at it. 

If you’re a developer or an aspiring technical writer looking to start contributing professionally, consider writing for us at We’re always looking for more writers and we’re open to people of all experience levels!

Finally, I’d love to hear some of your thoughts on writing as an engineer and what it takes to be a better writer. Leave a comment below or connect with me on Twitter.