DEV Community

Cover image for A Software Developer’s Guide to Writing
Ankur Tyagi
Ankur Tyagi

Posted on • Updated on • Originally published at theankurtyagi.com

A Software Developer’s Guide to Writing

The Ultimate Guide to Writing in Tech For a Developer

I started writing because I wanted to share my experiences with tech and needed to turn my life around. I loved ideas but had nobody to talk about them with. So my typical 9-5 colleagues mocked me when I brought up good topics.

> Three years later, I can say that writing on the Internet is among the best career decisions I’ve made.

This article includes insights that, over the past 3 years, have improved and increased the productivity of my writing.


What is Technical Writing?

Technical writing is the ability to write concisely and clearly about complex topics.

In tech, As a software developer, honing your writing skills can be the key to unlocking new opportunities and propelling your career to new heights.

  • Whether it's composing a compelling email to your colleagues.
  • Drafting a proposal for the next major project.
  • Expressing your thoughts clearly and concisely.
  • Sending a CFPs for your first conference.
  • Drafting a year-end review for your manager.
  • Sending a cold email or dm for an opportunity.

Writing effectively can open doors and help you make a greater impact within your organization.

So if you want to take your career to the next level, don't forget the importance of mastering the written word.

Writing gave you wings. It unlocked the potential of the Internet for your career.

Writing in Public is broadcasting your thoughts to the Internet to become a magnet for people and opportunities.


The Art of Storytelling in Tech Writing

  • Your blog should be written in such a way that your reader can use the content and feel as if they have learned something new after reading it.
  • You should take that complexity and break it down into logical steps and topics that will guide the reader.
  • Every story, we're taught in school, should have a beginning, a middle, and an end. The same is true for blogging.
  • People learn more from real stories than from being told.

Life is all about telling stories, we all have one, and we all adore it.


The Myth that Technical Writing is Easy Money

Early in my career (pre-tech writing), I realized that most people aren't good at communicating their ideas in writing.

Good money? Absolutely. Easy money? Not a chance.

In tech, Many beginners mistakenly believe that a target audience in writing is a single group when in fact it is incredibly diverse due to this well, there's more bad writing than good out there.

Writing or editing a blog post requires you to consider many factors, including grammar, style manuals, accessibility, accuracy, and consistency. It's a balancing act.

Grammarly perfect is one thing, but the ability to communicate clear information—especially information about a new product, establish integration with X and Y, or share what you have built in a new side project—requires years of practice.

To write effectively about a topic, extensive research is required. Strong research skills are required to develop your understanding and communicate with those with a limited understanding.


Feedback Request for Technical Writing

I used this strategy in my Twitter direct messages. I sent my drafts to established writers or developer advocates in IT.

Look at this screenshot from this year when I wrote about my journey as a developer advocate.

Image description

Image description


The Importance of Writing for a Developer

Strong writing skills are necessary for many roles in software engineering as remote work becomes more popular.

  • Long-form writing will help you become a better thinker and developer.
  • Long-form writing can help you build your personal brand.

For e.g: Imagine a developer, working on a new mobile app for a popular coffee chain. The app allows customers to order and pay for their drinks directly from their phones. The developer has spent countless hours coding and debugging the app to ensure it works smoothly. However, when the app is released, it quickly becomes clear that some major usability issues are causing customer frustration.

The developer knows they need to fix these issues as quickly as possible. Still, they also realize that they can't blindly make changes without a clear understanding of the problem. So, they take a step back and write a detailed report outlining the issues they've observed, along with proposed solutions for how to fix them.

The report is written and easy to understand, and it includes screenshots and other visual aids to help illustrate the problems and proposed solutions.

In this scenario, the developer's writing skills played a crucial role in clearly and effectively communicating the problems with the app and proposing solutions.

Without strong writing skills, it may have taken much longer to identify and fix the problems.

And doing long-term value blogging is a terrific strategy to attract more than simply readers. You'll also find potential clients and business partners stumbling across your work.

Public writing can have several second-order effects

  • Impact on your professional or personal brand
  • Networking opportunities
  • Increased visibility
  • Build your reputation
  • Engagement with a wider audience

Creating Engaging Headlines for Tech Content

Suppose you’ve ever been in the situation of trying to promote a technical product through a series of blog posts or articles. In that case, you’ll know what it’s like.

  • Make a promise and Be specific.
  • Use pop culture references: For example, "Loading like a boss: Tips for improving website speed"
  • Use strong verbs: Verbs like "discover," "unlock," and "transform" can add excitement and a sense of action to your headlines and subheadings. For example, "Discover the secret to optimizing your website's loading speed"
  • Use numbers and lists: Numbered lists and bullet points and easier to scan, so consider using them in your headlines and subheadings.

> For example, "Top 5 tips for improving your website's loading speed"

  • Use emojis: Emojis can add a playful and visual element to your headlines and subheadings and can help make your content more eye-catching and memorable. Just be sure to use them sparingly and appropriately to avoid overloading your readers with too many distractions.

> For example, "⏱️ Time to speed things up: Tips for optimizing website loading times"

More examples

  • "Tech troubleshooting 101: A beginner's guide to fixing common computer issues"
  • "The A-Z of HTML: A comprehensive guide to web development basics"
  • "Mastering the command line: Tips and tricks for working with Linux and Unix"

And remember, Professionals, aren't creating a single headline. They create many headlines.


Strategies for Overcoming Writer's Block

  • Break the task into smaller chunks: Instead of tackling the entire blog post at once, divide it into smaller, more manageable paragraphs.

For e.g: How I'm writing a book "The Blogging Developer: A Guide to Turning Your Passion for Code and Writing into a Profitable Side Income"

Image description

  • Set aside dedicated writing time: Block out a specific time each day or week to work on your writing. Having a consistent writing routine can help you stay focused and make progress.

  • Create a supportive writing environment: Find a quiet, distraction-free place to work, and consider using the Pomodoro Technique to help you stay focused.
  • Seek help when needed: Don't be afraid to ask for help if you feel stuck or overwhelmed. A colleague or mentor can provide valuable feedback.
  • Too many developers and writers believe that marketing is out of their league. But selling is a necessary part of life.

> Building a good audience will take time, no matter how good your writing is.

  • You can buy attention, but you can’t buy trust. It has to be earned, and that’s what writing makes it so precious.

Writing Tips for a Software Developer

  1. Identify your audience: Before you start writing, you must know who you are writing for. This will help you tailor your writing to your audience's needs and level of understanding.

  2. Use simple and clear language: Avoid jargon or complex language that your audience may not understand. Instead, use simple and clear language that is easy to read and understand.

  3. Organize your information: Make sure to organize your information in a logical and easy-to-follow manner. Use headings, subheadings, and lists to break up your text and make it easier to read.

  4. Include examples: Examples can be a great way to illustrate a concept and make it easier to understand. Try to include examples wherever appropriate to help your audience understand the information you are presenting.

  5. Be brief: Technical writing should be concise and to the point. Avoid including unnecessary information or repeating yourself.

  6. Use visuals: Visuals, such as diagrams, charts, and images can be a helpful way to supplement your text and make it easier to understand. Use visuals wherever appropriate to enhance your documentation.

  7. Review and revise: Always review and revise your writing before publishing it. This will help you to catch errors, clarify any confusing information, and improve the overall quality of your documentation.

I strongly recommend that you read Gergely's blog post on "Becoming a Better Writer as a Software Engineer."


How Writing Can Increase Opportunities

  • Technical writing can help developers to showcase their expertise and skills to potential employers or clients.
  • By writing technical articles, blog posts, or tutorials, developers can demonstrate their knowledge and experience in their field.

  • Technical writing help developers build a personal brand.
  • Technical writing improves their opportunities for networking, collaboration, and career advancement.
  • Technical writing can help developers to improve their communication and collaboration skills.

The Best Way to Find Writing Opportunities

  • Network with people in DMs
  • Show your expertise
  • Show your work
  • Deliver the best technical content
  • Ask your favorite DevRel Advocate if they need a good writer, You can help to build the next integration, docs or that pending blog post.

Consider the following real-world example

A Full-time technical writer/developer advocate/developer relations is getting on an average of $30-90k in Asia and 2-4x that in the US/EMEA.

Most of these businesses do not want to spend their weeks writing content. Even if they manage to find a great person and get one good piece of content every week from them, that's $1k-$5k per technical blog.

And maintaining similar volume/velocity/quality internally is difficult since the best technical employees get burned out soon from generating content and/or get pulled into other projects because no marketing team ever has enough technical people.

This is where you can fill a gap in their backlog and become a good player from the outside & it's a win-win for both business and you as a creator.


Conclusion

Daniel's idea for getting started with writing is brilliant.

> The key to success is to simply begin writing. No tricks or shortcuts are needed - just start creating.

Ask yourself the following questions to help you stay focused to write more.

  • What do I do better than other writers in tech?
  • What can I do for a long time in blogging?
  • Where do I want to take my blogging skills?

Play not to lose; Instead to win.

You can learn, help, and earn simultaneously as a technical writer.

As you embark on your writing journey, it's important to remember to think outside the box and try new things.

Don't be afraid to take risks and challenge yourself. Whether it's experimenting with new writing styles, exploring new topics, or finding unique ways to engage your readers, the key is to keep an open mind and be willing to try new things.

Who knows what amazing opportunities and experiences may come your way if you're willing to step outside your comfort zone and take a chance?

So don't be afraid to take a chance and see where it leads you. Happy writing!

If you enjoyed the article, you'll like my newsletter:

Join here: 2-1-1 Career Growth Newsletter


This blog post is a small excerpt from my most recent book; if you enjoy it, you will enjoy the book. More than 140 people pre-ordered.

Image description

You can pre-order your copy today.

Image description

Oldest comments (22)

Collapse
 
andrewbaisden profile image
Andrew Baisden

Great resource thanks for sharing with the community.

Collapse
 
tyaga001 profile image
Ankur Tyagi

Thank you so much for the kind words @andrewbaisden

Collapse
 
bretbernhoft profile image
Bret Bernhoft

I enjoy blogging, as it offers me an opportunity to experiment with content ideas, and to receive feedback from any audience that might form around said media. So this article is a welcomed sight. Thank you for posting this information.

Collapse
 
tyaga001 profile image
Ankur Tyagi

@bretbernhoft You're welcome! I'm glad that my writing was able to provide value for you. Sharing my knowledge and experiences with others is something that I truly enjoy.

Collapse
 
orix profile image
Waleedh Nihal

Same!

Collapse
 
connectwithajayy profile image
Ajay Gupta

Thanks, Actually a good blog, and felt a new perspective to grow.

Collapse
 
tyaga001 profile image
Ankur Tyagi

Thank you very much, I appreciate your feedback.

Collapse
 
dastasoft profile image
dastasoft

As a person who started writing not so long ago I totally agree with what you are saying here.

For me at least the hardest part of all this might be that visibility/content marketing in the form of short tweets, it's something I need to try but I know it's my weakest point right now.

Collapse
 
tyaga001 profile image
Ankur Tyagi

@dastasoft Thank you, I appreciate your feedback.

Collapse
 
bomaaaa profile image
Bomaaaa

Thank you very much for sharing!

Collapse
 
wasava profile image
vasava

Outstanding work

Collapse
 
tyaga001 profile image
Ankur Tyagi

@wasava Thank you very much, I appreciate your feedback.

Collapse
 
nikitababko profile image
Nikita Babko

Awesome. Very informative 👍

Collapse
 
tyaga001 profile image
Ankur Tyagi

@nikitababko Thank you very much 🙌

Collapse
 
tonylisanti profile image
Tony Lisanti

Thanks for the insightful article. You mention to not set up a personal blog. Can you please explain why?

Collapse
 
tyaga001 profile image
Ankur Tyagi

@tonylisanti -: IHMO, why a new writer shouldn't set up a personal blog when starting writing:

  1. - It can be time-consuming and costly to maintain a blog.
  2. - It can be difficult to build a following for your personal blog.
  3. - They'll need to invest time and effort into promoting their blog.

For example, in my DM someone sent me this on Twitter last year.
Image description

But once you are able to get some good posts and views, start moving towards your own place instead of a rental place but keep them both. As it's a win-win for everyone. Just like this post, originally posted on my website but I always cross-post on DevTO.

Owner of blog space >> Rental space!

Hope this helps.

Collapse
 
aowendev profile image
Andrew Owen

@tonylisanti

Having been paid to write for over three decades, I'd argue that the best way to get better is by doing it. If you're a developer, then you should find it easy to set up a free personal website with a blog using static site generators, headless CMS and serverless hosting (I've got a blog post on how to do that). But instead of that, you could just start posting here on dev.to.

I wouldn't be overly concerned about building a following. Write what you want to write about and if it's any good, it will find an audience. If you're running your own site, do set up analytics so that you can see what works and what doesn't.

The easiest way to promote a blog is to share it on socials when you have a new post. Use four well-chosen hashtags and a short description of the content. And never be afraid to shamelessly promote your own content (andrewowen.net/search/?query=writing).

Collapse
 
sylent3524 profile image
sylent3524

Coincidentally I just finished my first university lecture on technical writing. This post is very welcoming to the subject!

Collapse
 
fruntend profile image
fruntend • Edited

Сongratulations 🥳! Your article hit the top posts for the week - dev.to/fruntend/top-10-posts-for-f...
Keep it up 👍

Collapse
 
muhammadiqbalid83 profile image
Muhammad Iqbal

thanks for information

Collapse
 
nikki_eke profile image
Nikki Eke

This is such a resourceful article. I learnt some things I'm going to start implementing right away. Thank you for sharing!

Collapse
 
tyaga001 profile image
Ankur Tyagi

@nikki_eke Thank you very much, I appreciate your feedback.