Words Over Code: Grow Your Impact And Career Through Writing
Why Should You Improve Your Writing?
We write all day long. Engineers will write pull request descriptions, JIRA tickets, Slack messages, RFC’s, design documents, etc. We probably spend significantly more time writing words to our colleagues than we do writing code. But how often do you find yourself working on your writing or learning new writing skills compared to learning a new programming language?
I would bet writing is a very overlooked skill that most of us take for granted. Did you ever study it formally in school? We write all day long but we don’t really think about how we are writing or what good writing is. Given the ubiquity of writing and the fact we’ve likely neglected developing this skill, we can see very quick improvement with just a little bit of effort. All it takes is consistently applying a few simple techniques to start seeing results.
But.. ChatGPT
With generative AI like ChatGPT, why bother becoming a good writer? Pulitzer prize winning author David McCullough said:
“Writing is thinking. To write well is to think clearly. That’s why it’s so hard.”
Offloading your work to ChatGPT here robs you of the forced clarity that putting your thoughts down into words will offer. Drafting a message or fleshing out an idea by writing it in a document for yourself first, is a crucial step towards developing the message you want to send. This step can not be skipped.
ChatGPT might be able to help you refine your thought or message. You can ask AI to condense it, improve the grammar, use shorter sentences, etc. But you must do the crucial task of developing the coherent message that you wish to convey to your reader.
Using a LLM to write for you is lazy and painfully obvious to your reader if all you do is copy and paste a response. It’s never been impressive to write a lot which is what these models are good at doing. As we drown in a sea of AI generated garbage, writing well will stand out even more. It will be more impressive and critical to respect your reader’s time by writing concisely and clearly. To be concise and simple in your writing requires you to do the work up front to break things down. These tools can help us in our writing but are not a substitute for becoming a better writer and better thinker yourself.
Career Growth
Writing well is important for career growth. The more senior you become, the more you will rely on communicating ideas. You will need to ensure your writing is easily consumed and understood so the people working with you can deliver the project. Writing is also a terrific way to scale yourself. You write something once and it can be read over and over by many people. Finally, writing will help you become a better thinker. Writing well will force you to deeply understand and refine your message to the point where it is as simple as possible.
Writing is a powerful and impactful but often neglected skill. With a little bit of effort and awareness we can drastically improve our ability to think and to communicate.
What is Good Writing?
The core principle of good writing is to respect your reader. This explanation is what works for me and I am by no means an expert. But it has proven very useful in my work and I think it can help other folks too.
Respect their time, respect their attention, respect them as people. All the tips on how to write well come out of this core idea. Josh Bernoff of the book Writing Without BS calls this the iron imperative and says to “treat your readers time as more important than your own.”
From various other books and blog posts on writing, I’ve organized many tips and techniques on writing well that let you respect your reader into three categories. Good writing is:
Clear
Concise
Kind
Clear means it is easy for your reader to understand your message and to consume your writing. They don’t have to skip around, they aren’t left with questions, they aren’t taking notes while they read just to understand your point. It’s clear what your message or your ask is.
Concise implies your writing is short and simple. You aren’t overly verbose. You aren’t using big words without purpose. You are direct and to the point, respecting your reader’s time. We all have too much information sent to us each day. Writers that cut to the point as fast as possible are appreciated.
Kind means you have empathy for your readers. You understand humans are different. Your tone is kind and supportive. Your language is inclusive because it costs you nothing to use respectful language. You recognize the different contexts or set of priorities other people may be operating under. You value the relationships that can be built with good writing.
How to Write Well
Good writing is when you respect your reader. You do the work up front as the writer to make it easy on your reader. This means your message is clear, concise, and kind. The reader simply flows over your words because you found the most elegant way to express your message.
Clear
Being clear means being direct. Put your main point first. The reader should know exactly what the intent behind your writing is. You can even summarize your writing by repeating your main point at the end. Use language like I, we, you, that makes it clear who is supposed to do what.
Annotating parts of your message can be helpful in some contexts. In the case of Pull Requests, design documents, or even just providing feedback to colleagues - it can be helpful to preface your comments. For example, when soliciting feedback on a PR you can say something like “review this part to make sure the business logic is correct.” When you are reviewing a PR you can point out that this is just a nit-pick for small things you don’t really care to change or call out “hey, this is a bigger concern, should we even be solving this problem?”. Annotating your feedback or your asks on larger forms of writing give your reader a clear call to action or help set the context to understand your feedback.
Good writing should be organized well. Make things easy to skim for your reader. Use headings, sub-headings, lists, and make use of bolding text. Not everyone has the same context or needs the same level of depth from your writing. Make it easy for folks to skip around and find what they are looking for.
Concise
Being concise means your writing is as short as possible and cuts to the point. Use as few words as possible to get your point across. Remove words that don’t add to the meaning. Be more direct. Remove should/can from your writing. Instead of saying ‘You should save this file to your home directory’, say ‘Save the file to your home directory.’
Limit the amount of jargon you use. It’s OK in some cases when you know your audience well and jargon can be more concise. But in general, use simple words in short sentences. The goal is to communicate, not demonstrate your intellect.
Use the active voice when writing. This means in your sentences, the subject is doing the thing. For example, ‘I wrote the code’ is active. Where, ‘the code was written by me’, is passive.
Don’t hedge your statements, be bold and opinionated. Adverbs and other qualifying words can make you sound non-committal. By being more assertive in your message folks will either agree or be prompted to disagree. When you hedge and say ‘maybe we could do X’, people are less inclined to respond.
Kind
Being kind means you keep people and the relationships you build in mind when communicating. You should put people first when communicating at work. Companies change over the course of your career but relationships can last. Spend the time to ensure your communication is kind. Ensure you convey a good, positive tone. Make use of emojis. Be polite. Try to add a sprinkle of humor when appropriate.
Have empathy for your audience. Understand everyone has a different perspective, different context, and a different background than you. Tailor your message accordingly. When communicating, realize they might not have the same context you do. Clarify this and provide follow up if necessary.
Use inclusive language. It costs you nothing to be kind with words. Just because it might not upset you doesn’t mean certain words don’t have an impact on someone else. Understand there is a difference between your intent and the impact felt by someone. If you make a mistake, apologize for your impact and learn from it.
Provide feedback when appropriate. Peer reviews are an excellent tool but only if your reviewers have the courage to share something meaningful. You can still be kind here but if you aren’t sure what to share, think, why is this person not at the next level yet? What can they do to be more awesome? It helps someone grow, this is kindness.
Action Plan
Writing is a skill. And just like you would improve any other skill, it takes time to get better. The most important thing you can do is to start making a conscious effort to improve your writing. Spend a little extra time with what you are writing.
The next time you need to write follow these steps:
1. Think
What is my ask? Spend time writing to yourself to clarify, simplify, and refine your main message. Do the work up front so your reader does not have to.
Who is my audience? Tailor your message with the appropriate context and tone for your intended recipient(s).
2. Write
Clear
Concise
Kind
3. Review
Take the time to review what you wrote. Is your message clear?
Remove as much as you can. Get your point across as simply as possible.
After you write something, pause, take the time to review it with this framework in mind. This is the most important part of becoming a better writer - taking the time to review/ edit/ improve what you wrote.
Summary
Good writing is when you respect your reader. This can be implemented by making sure your writing is:
Clear - Your main point is easy to understand and put first.
Concise - You say it as succinctly as you can.
Kind - You recognize the human reading your message.
To put this into practice and make it a habit, be sure to think before and review after you write.
As with any advice though, take the ideas and tips here that are useful to you and discard the rest. Find the style of “good writing” that feels authentic to you.