The Reason Software Engineers Should Write

I’ve been thinking a lot about writing lately. I recently left a career as a startup CTO to write full-time, so when people ask me things like, “Why should software engineers know how to write?” I have a lot of thoughts. Rather than write yet another listicle (1, 2, 3, 4), I am going to boil it down to one simple reason:

You should write to increase your level of influence.

Why Influence Matters

Whether you strive to be promoted within your organization or be fawned over by the coolest tech companies, the fastest path to success is making the right people aware of you. In one of the best essays of career advice for programmers, Patrick McKenzie points out:

“Most jobs are never available publicly, just like most worthwhile candidates are not available publicly. Information about the position travels at approximately the speed of beer, sometimes lubricated by email.” - Patrick McKenzie, Don’t Call Yourself a Programmer

Unfortunately, just being the “best” programmer around isn’t going to get you talked about in a bar (and it’s subjective anyway). Ben McCormick points out:

“Once somebody hits a minimum threshold of technical skill to hold a job in the industry, about 80% of their ability to succeed in Software Development is determined by their communication and people skills, not their technical abilities.” - Ben McCormick

My experience supports Patrick’s and Ben’s assertions, so now the question is, how can you become one of the people whose name comes up before a job is publicly available?

The right people have to know you. You have to have the right kind of influence.

Levels of Writing Influence

“The difference between a tolerable programmer and a great programmer is not how many programming languages they know…It’s whether they can communicate their ideas. By persuading other people, they get leverage.” - Joel Spolsky, Co-founder of StackOverflow

If you buy my assertion that influence is important in your career as a software developer, the next step is for me to convince you that writing will actually increase your influence. In fact, not all writing will work. The kind of writing you do will make a massive difference on the level and kind of influence you gain.

Let’s take a look at the different levels of influence you can achieve as a software developer and the kinds of writing you need to do to achieve them.

1. Willing Participant

Participants are not influential. They don’t realize it, but they have very little control over their career and are likely to go through a period of unemployment and grueling job interviews every time they need a new job. The only writing a Willing Participant will do is what’s required of them: they’ll respond to Slack messages and emails; they’ll dutifully enter their progress report every day; they might leave a sticky note on someone’s desk (or the digital equivalent) when they want to have a protracted discussion about an issue.

If this is you, don’t be discouraged. We all start our careers as Willing Participants. With most software engineering jobs staying remote for the foreseeable future, the minimum level of writing ability is likely to increase, but just checking the box isn’t going to put your name on the tip of your next boss’ tongue.

2. Organizational Teacher

“Every time you find yourself following the manual instead of writing the manual, you’re avoiding the anguish and giving in to the resistance.” - Seth Godin, Linchpin

Most software engineers live in this zone. Organizational Teachers write documentation, technical specifications, style guides, testing criteria, bug reports, and internal knowledge base articles. While this gives you a little influence over how your team (and possibly some adjacent teams) does its job, it’s unlikely that anyone outside your company will hear about your work.

The good thing about being in this zone is that it’s a safe place to practice. Nobody’s going to berate you for your typos (at least, I hope not), and other stakeholders will review most of your writing before it’s made generally available.

The downside to being an Organizational Teacher is that it’s pretty much table stakes for senior engineers. You’re not going to stand out for it, and you probably won’t get your name attached to it (unless it’s buried in your commit history). Hone your writing skills as an Organizational Teacher, and once you feel more comfortable, move up the ladder.

3. Organizational Influencer

As you move into an (official or unofficial) leadership role, you’ll start to do more writing at the Organizational Influencer level. This writing includes setting hiring criteria, documenting tradeoffs between complex technical decisions, creating training materials, and setting budgets. These documents will be seen by people above and below your station and will help get you noticed for future promotions.

Many software developers assume that they should not attempt to contribute this kind of writing unless asked. This is incorrect.

For example, if you’re given a new project, you have a professional obligation to report shortcomings in the design. When you report these issues, don’t just write a Slack message, “This won’t work.” Document the tradeoffs between the proposed solution and one that you’ve seen work elsewhere. Most people don’t do this because it’s hard, and that’s why they don’t have much influence.

Organizational Influencers are helping set the direction for at least a small part of the business, and they’ll end up doing more writing than those at the previous two levels. Software developers who make it to this level will be eligible for more internal promotions, interesting lateral moves, and a general increase in respect. Organizational Influencers will also start to gain the confidence to start writing externally.

4. External Teacher

“Writing is hard. People spend their entire lives learning how to write effectively. It isn’t something you can fake. It isn’t something you can buy. You have to work at it. That’s exactly why people who are afraid they can’t write should be blogging. It’s exercise.” - Jeff Atwood, Co-founder of StackOverflow

Despite the prevalence of Medium and Dev.to, surprisingly few software engineers ever write publicly. External Teachers generally start by writing technical case studies, public documentation, and walkthroughs. This is where software developers can begin to publicly display their knowledge and build a personal brand.

I’ll put a big caveat here and say that writing a few tutorials will not immediately make employers hunt you down. I’ve written dozens of technical tutorials over the years, and only a couple of them led directly to an employment discussion (neither of which worked out). Writing publicly is the first step in building a reputation, but more importantly, it gives you a great resource to point to when an employer asks you about a specific technical experience you’ve had.

The hard part about becoming an External Teacher is that it’s scary, and you’re likely to suck at first. People naturally avoid doing things they’re bad at, but doing scary things is an essential part of gaining influence.

If you overcome the fear of writing publicly and you start to tell people about your writing, you’ll probably be surprised by the encouragement you get. People will root for you when you do something they’re scared to do themselves.

5. External Influencer

So few people achieve the level of External Influencer that just attempting this sort of writing puts you in a tiny, standout class of people. Unlike the External Teacher, who sticks to irrefutable facts and rehashes of existing knowledge, the External Influencer has a strong point of view. They write from deep experience, and their writing influences the decisions that others make.

Some of the External Influencers you’ve probably heard of include Martin Fowler, “Uncle” Bob Martin, and Eric Evans. When they write something, thousands of programmers listen, and their books have shaped decades of software architecture.

There are degrees to all the influence levels in this model. You don’t have to be Uncle Bob to be an External Influencer; you just need to start applying your technical experience to larger business challenges in a public forum. For example, Eric Evans created Domain-Driven Design to help businesses build better software by making it more closely resemble the underlying domain model. If you’ve spent years solving a particular set of problems, you probably have at least a few issues you could get on a soapbox about. These are likely your platform for becoming an External Influencer.

While it sounds great, acting like an External Influencer is even scarier than being an External Teacher. Not only does your writing have to be factually accurate and coherent, but you’re also opening your ideas to public criticism. Nobody likes to get slammed on the internet, but the upside can be huge if your work is well-received. Do you think Martin Fowler would ever have trouble getting a job if he decided to leave ThoughtWorks? I’m pretty sure he could (literally) write his own job description just about anywhere.

Write Above Your Level

By this point, I hope I’ve convinced you that influence is an important part of advancing your software development career and that writing can help you gain this influence. My final encouragement to engineers who want to become better writers is to push beyond your current level. It will be uncomfortable, but it’s also one of the best ways to take control of your career. Let me know if I can help.

Blog

The Reason Software Engineers Should Write

Karl L. Hughes