Why Write

Why Write

This article was originally published on Offerzen. Big shout out to Chris & Darsha for their insights via editing :)

For self-taught junior developers, it can be hard to stand out in a competitive industry. I’ve found that improving my writing skills has helped me stand out, improved my technical skills and made my networking more effective.

Quincy Larson tweeted “Build your skills. Build your reputation. Build your network. Your career success depends on all three of these.” Writing in public spaces contributes to all three! Here’s how writing in public spaces, such as blogs, internal company communication spaces and documentation, has helped me.

OfferZen_How-Writing-Boosts-My-Developer-Career_inner-article

Writing equips you for a remote-first world

It’s hard to separate asynchronous communication from remote work. As reported by OfferZen’s State of the Software Developer Nation Report, a whopping 92% of developers in South Africa have the option to work from home - 51% of those in a remote-first set-up.

The async nature of remote work will have all of us doing some sort of writing on a daily basis - including Slack messages, emails, pull requests, code reviews, user stories, ticket descriptions, and other project management tasks. Writing helps you structure your thoughts and effectively communicate in an async setting.

Learning to write well also makes you more effective at communicating with busy people. This ensures that your communication is clear and that you’re getting all the relevant information across.

Tips for an effective message when seeking assistance

Software engineering is very much a team sport. Quite often, I rely on input from fellow engineers, designers, and the product and platform teams. I find it safe to assume my colleagues are busy, so I’ve used this resource to help me structure messages when I ask for help.

I generally structure such messages like this:

  • Descriptive Subject line or title. A good subject line gives context before your reader even opens the message.
  • Concise sentences and paragraphs, with titles where necessary. Put the most important information first and upfront.
  • Use lists to enumerate questions if there are many.
  • Make it obvious what the meat of the message is.

This Request for Comment (RFC) is structured in the same way that I think is effective for asking senior teammates for help. The idea is to preserve/respect their time and give them all the context they need to help you.

Another example is this document that evolved as I debugged a problem with the help of a few senior mates.

Here are some templates you can refer to:

The level of detail in such documents is contextual and determined by your intended audience.

This structure is useful for async communication because it:

  • includes a detailed overview of how the code is structured,
  • states the problem,
  • shows how I tried to solve the issue,
  • and then shows the eventual solution.

This makes it easier for the reader to parse, quickly gain context, and help you.

Beyond async communications, the ability to structure an “argument” can extend to interviewing. I have been in multiple interviews where I’ve had to answer the behavioural question along the lines of: “Tell me about a time you had a difficult technical problem and how you solved it?” and was able to do so using the technique above: context, problem and solution.

Improving your writing can improve your code

Ultimately, your code needs to be maintained, meaning you’re writing it for a person in the future - you or someone else. Part of being a good writer is being a clear communicator. That skill transfers to how you write your code, as you’re better at expressing your intention when you write well.

Clear writing reduces cognitive load on the reader

Clear writing aims to reduce the cognitive load required to parse the important bits you’re trying to convey. Some tactics for reducing cognitive load when writing are:

I think the principle of reducing cognitive load when coding can be practised by properly naming variables/methods (instead of using short, meaningless names, go for descriptive names that give as much context as needed), files, and type definitions. These are all ways of communicating intent to other developers.

My folder structure has definitely improved as a result of working on my writing skills. This is because a big part of writing is organising your documents intuitively and in an actionable manner.

Know your audience

Google’s technical writing course emphasises that you should know your audience well before you set out to write. This line of thinking can be applied to code as well.

My general rule of thumb is to try and write for the lowest common denominator. If you can write your code for the most junior team member to understand easily - usually me, when I’m writing - you can cater for the widest audience possible. This frees your future self from having to spend time supporting that artefact by constantly having to answer questions about it.

Good programmers value code that is easy to understand, and thus cheap to use and modify. - Martin Fowler

Writing makes non-coding work tasks second nature

Fact: Making software doesn’t mean you’ll spend all your days cranking out code. A good day for me is 4 to 6 out of 8 hours spent writing code. The rest of the day is spent on reviews, meetings and communicating with fellow teammates.

Building good writing habits can vastly improve your quality of life at work, as a lot of tasks that aren’t coding can directly benefit from the skill.

Making a habit of keeping notes as you work can be helpful, as it allows you to repurpose that writing

The various forms of writing that a developer may use:

  • Request For Comment (RFC). A versatile document that is useful whenever you need to solicit input from others. I use RFCs when I’m conflicted about a technology choice, when I want to request process changes, and when I’m stuck on some work.
  • Architecture Decision Record (ADR). ADRs help to give as much relevant context as possible to the next developer, which means your ADRs don’t have to look exactly the same every time. The templates are just there to guide you. I like to keep these documents as markdowns in the same folder as the relevant code.
  • Onboarding documents. It’s good practice to ensure these are kept up to date even after you join a team. It’s easy for onboarding docs to drift out of sync when the whole team is productive in their tech stack and not reliant on them. A good first task after joining a team is to ensure the onboarding docs are in sync with reality.
  • Code review - this is a very big one and a part of daily workflow. Good git commit messages can make the reviewer’s life a little easier by providing well-described checkpoints that group related code.
  • Communicating with other stakeholders that aren’t developers - POs, business analysts, sales, marketing etc. Knowing your audience and their incentives is helpful here. That informs the level of detail you share in your technical updates.
  • Meeting agenda and notes written ahead of time. This resource is a game changer for improving the quality of meetings - it’s known as the 6-pager at Amazon.

This list isn’t exhaustive, but I think it illustrates some areas where good writing skills are useful for your developer job.

Writing sets you up for senior roles

Every senior engineer I’ve crossed paths with spends a decent portion of their time writing. Sarah Drasner’s Career Ladders helps to give an idea of how your writing commitments will increase as you become more senior.

As a knowledge worker, writing is a skill you’ll need to rely on more and more as you work your way up in your career. I can even go as far as saying I’ve observed that clear writing and communication will become an expected part of your job description. Satya Nadella says “You can’t call yourself a leader by coming into a situation that is by nature uncertain, ambiguous—and create confusion. You have to create clarity where none exists.”

For this reason, I think writing is worth improving early on in your career when you have more time to sharpen this skill. Because you likely won’t be leading anyone yet, learning how to write early in your career gives you a chance to learn in an environment with lower pressure, where no one expects you to be great at it already.

Software development career coach Jayme Edwards speaks about senior developers documenting chosen code patterns. The nice thing is you don’t have to wait until you’re senior to start doing this. I already spend time trying to document patterns in our codebase and send it up to other engineers for review.

Writing demonstrates your expertise

Scott Hanselman says, “email is where keystrokes go to die”, and that thought can be applied to instant messaging, which we use a lot when collaborating with other developers, such as Slack, Discord and other private spaces.

So instead of letting an interesting topic sit in your email inbox, try and think how you could use this opportunity to improve your writing. For example, when a friend asks me a thought-provoking question that I think is helpful for more than one person - usually it is if it’s a technical question - I’ll write a blog post or document that I can share via URL and send that instead.

That way, if someone asks the same question, I can just send that link. I don’t have to answer the same question twice, and having that writing in a public space is hopefully doing some good SEO for my name.

Here are a few examples of where I wrote blog posts based on questions I was asked:

Improving Personal Branding and establishing domain expertise

Public writing gives you an increased chance of running into interesting people or of serendipity. So many conversations with interesting people in the software and music industry have started because of something I wrote.

I tend to be self-indulgent and write about stuff I like, meaning you’ll find a lot of YouTube videos embedded on my website. For weeks, I wrote notes based on a YouTube channel I was really enjoying, and at some point decided to email the creator to give him thanks for educating me. His response made my day:

“Hey Guide!

Glad to hear you’re enjoying the videos. I actually came across your website recently! I have a Google Alert set up for “dub monitor” and it came up so I checked it out. Really appreciate what you’re doing.”

The above is merely a single example of how writing can help scale one’s personal brand by making an introduction for me while I wasn’t even in the room.

Writing is also an opportunity to take control of your career by picking a niche, working to establish domain expertise in that niche and building a traceable track record. This can be done via blogging, creating screencasts for YouTube, podcasting or posting social media content.

As mentioned before, written documents are reusable artefacts. This means you can write once and deploy everywhere!

Present your work experience and interests more effectively

Good writing can help demonstrate your skills and experience, which is especially important when you have little or no formal work experience. A well-presented record can help you stand out when looking for work.

Writing shows a commitment to learning as it communicates that “I’m not here to mess around or for a quick buck. I’m doing this for real”. As a self-taught engineer, this is a good way of earning the trust and confidence of people that are hiring.

A handful of people who’ve interviewed me mentioned explicitly that the writing left a good impression.

I published notes on front-end topics and challenges for about six months before I got my first job. Most, if not all, interviews I’ve been in have given me a chance to share my writing, and a handful of people who’ve interviewed me mentioned explicitly that the writing left a good impression. And it’s totally okay to use your past writing as supporting answers to interview questions. I’ve done a lot of that, and every time, it’s been encouraged by interviewers.

Written records allow you to show the impact you have had and the work you’ve done a lot better than a resume could. That gives you an extra edge, especially if, like me, you may find it a bit difficult to come up with coherent and fully fleshed-out answers on the spot.

I like to think of my writing as the equivalent of a university transcript - displaying my competence across a wide array of related subjects. It has allowed me to explore topics I wouldn’t otherwise do in my day-to-day job as a front-end engineer. With no work experience, if I want to pivot into backend engineering or UX research, I can publish my notes and experiments as I learn so that I have a track record by the time I have to convince someone to give me money in exchange for the services.

Take your time to show off how awesome of a developer you are:

True insight almost never comes to even the smartest candidates in the timeframe of an interview.

Resources