A Software Developer’s Guide to Writing
The Ultimate Guide to Writing in Tech For a Developer
9 min read
Table of contents
- What is Technical Writing?
- The Art of Storytelling in Tech Writing
- The Myth that Technical Writing is Easy Money
- Feedback Request for Technical Writing
- The Importance of Writing for a Developer
- Creating Engaging Headlines for Tech Content
- Strategies for Overcoming Writer's Block
- Writing Tips for a Software Developer
- How Writing Can Increase Opportunities
- The Best Way to Find Writing Opportunities
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.
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
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"
"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"
- 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
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.
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.
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.
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.
Be brief: Technical writing should be concise and to the point. Avoid including unnecessary information or repeating yourself.
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.
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.
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
Did you find this article valuable?
Support Ankur Tyagi by becoming a sponsor. Any amount is appreciated!