A Software Developer’s Guide to Writing

A Software Developer’s Guide to Writing
Share on facebook
Share on twitter
Share on pinterest

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
  • 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

  1. “Tech troubleshooting 101: A beginner’s guide to fixing common computer issues”
  2. “The A-Z of HTML: A comprehensive guide to web development basics”
  3. “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

  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!

Subscribe to our Newsletter

Join my email list for career and mentorship advice and more!


Share this post with your friends

Share on facebook
Share on twitter
Share on linkedin

Comments are closed.

Articles you may like

Why You Should Learn ReactJS

Why You Should Learn ReactJS

Introduces support for async/awaits in Server Components. Write Server Components using standard JavaScript await syntax by defining your component as an async function.

Read More »