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 simple possible way to express what need to say.
Clear
Being clear means being direct. Put your main ask or your main point first. The reader should know exactly what the intent behind your writing is. You can even summarize your writing be 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 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 their 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.