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.
David Perell@david_perellIn school, we mistakenly learn that good writers are the ones who follow the rules of grammar. Meanwhile, many of the most popular Reddit posts are littered with spelling errors, but nobody cares because the ideas are so captivating.
Time for a change.05:05 AM - 12 Dec 2022
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
Nathan Baschez 📧@nbashawWhen I sent people drafts of my posts for feedback, I never knew what to say if they asked "what kind of feedback would be helpful?"
Now I use the "ABCD" framework:
- what's Awesome?
- what's Boring?
- what's Confusing?
- what Didn't you believe?
(credit to @shl for this!)21:42 PM - 09 Mar 2020
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
- 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"
- "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"
Ankur💻🎧💪@theankurtyagiMy writing is now making $2,500/month in revenue.
- I have 5K+ subscribers.
- I get 2-3 inbound leads every week.
Past: I published 100+ average posts.
Now: I publish 2-3 new quality blog posts every month.
Start a Blog in 2023; It's truly an amazing side income opportunity.12:08 PM - 07 Jan 2023
- 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.
I started shutting my phone off every night at 10:00PM, When I wake up at 5:00AM I do write, edit, rewrite my latest book 📕 for next 2 hours & then finally turn the phone back on after 7:00 AM.
Best way to start a day, try this, you’ll fall in love with writing!19:05 PM - 15 Dec 2022
- 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
Ankur💻🎧💪@theankurtyagi7 tips for better writing:
1- Great writing is actually re-writing.
2- Simple words & clear layout.
3- Simple & clean language.
4- Write like you’re talking to a person.
5- Don't try to pretend to be cool.
6- Support ideas with examples.
7- Vary your sentence lengths.20:04 PM - 14 Dec 2022
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.
Ankur💻🎧💪@theankurtyagiWriting strategy for beginners:
1. Learn a skill that will always be in demand e.g. React
2. Don't set up a personal blog.
3. Start writing articles & show your knowledge.
4. Repurpose articles into tweets.
5. Build a network with smart people.
6. Send 10 cold DM/Emails.08:06 AM - 14 Dec 2022
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.
Aman Mittal ⚛️☕🖖@TheAnkurTyagi Blogging had a significant impact on my career. It helped me with networking, starting conversations, building friendships, and getting opportunities.12:37 PM - 28 Jan 2022
- 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.
Daniel VassalloInstead of writing a book, write a blog post.
Instead of writing a blog post, write a tweet.
Keep cutting scope until it feels very easy.
Once you have a few tweets, a blog post becomes easy.
Once you have a few blog posts, a book becomes easy.19:08 PM - 10 Sep 2022
> 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.
You can pre-order your copy today.
Top comments (22)
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.
@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.
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.
@dastasoft Thank you, I appreciate your feedback.
Great resource thanks for sharing with the community.
Thank you so much for the kind words @andrewbaisden
Thanks for the insightful article. You mention to not set up a personal blog. Can you please explain why?
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).
@tonylisanti -: IHMO, why a new writer shouldn't set up a personal blog when starting writing:
For example, in my DM someone sent me this on Twitter last year.
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.
Hope this helps.
Awesome. Very informative 👍
@nikitababko Thank you very much 🙌
Thanks, Actually a good blog, and felt a new perspective to grow.
Thank you very much, I appreciate your feedback.
thanks for information
Сongratulations 🥳! Your article hit the top posts for the week - dev.to/fruntend/top-10-posts-for-f...
Keep it up 👍
Coincidentally I just finished my first university lecture on technical writing. This post is very welcoming to the subject!
Thank you very much for sharing!
This is such a resourceful article. I learnt some things I'm going to start implementing right away. Thank you for sharing!
@nikki_eke Thank you very much, I appreciate your feedback.
@wasava Thank you very much, I appreciate your feedback.