Why write?

This is going to be one of those “why do I write?” kind of articles. I’ve definitely read a few of these over the years but I still think it’s worth sharing my own story.

2015 was the first time I, personally, felt the impact of my writing. Prior to that, I had written technical design and various other documents that had helped my team. My managers were positive and supportive. My code style and team practices documents became standard documents for new hires but my writing didn’t go much beyond my team. In 2015, I wrote a little article that went beyond my team, and that was the first time I realized that I could have an impact by writing. From that time, and in the years that followed, I learned I could meet people, influence, clarify my own thinking, and have fun simply by writing things down.

Writing helps me to meet and get to know people. In 2015, I had been reading lots about microservices and when I compared it with how we were deploying software, I realized that although we said microservices, we were still deploying a monolith of a hundred small services. I saw benefits to changing our current model so I wrote my thoughts on a wiki to see what my team thought. At that company, no one was writing stuff like that on the wiki, and it accidentally attracted the attention of the architecture group and was passed around to other senior people on other dev teams that I had never worked with. As a result of that little article, I was invited to present my ideas to other teams and meet other devs and chat about it. Actually, many people had the same thoughts. One dev in particular reached out and invited me to lunch so we could talk more about it. I don’t know what came of all that talk, I had accepted a role at a different company shortly after. The lesson stayed with me though, that I could meet people by writing.

My written work lasts much longer than I do. I worked 8 years, at my last job, and it’s quite likely that some of my code is still in production but I know that my writing on the internal wiki is still having an impact. It’s been almost a year since I resigned but I still occasionally get messages about things I wrote:

Was reading [your article] - loved the way you wrote with honesty - first document in 6 yrs [at this company] - that’s written with such honesty and integrity. I’ll read all posts on Lloyd’s thoughts, promise!

I enjoyed reading your blog on the wiki. Thanks!

I remember stumbling across your internal blog and spending an afternoon reading through some of your posts! They were very insightful and really made me think about being more empathetic towards others

Mostly I would write personal anecdotes and opinions on work or company culture or books I’ve read and what I’ve learned. I didn’t promote my writing much, I would leave links here or there or bring them up for discussion at team meetings, but it was enough. Even though I don’t work there I am still able to have an impact, hopefully a positive one, because I left a written footprint.

Writing helps clarify my own thinking. For example, when I was writing about my DOOM engine performance, I would write a sentence and realize I needed data to back it up or illustrate the point. Then I would collect that data but realize there are more improvements I could make or it would lead me to ask more questions. The act of writing produces a better outcome because I have to double check my work. At other times in my career, I’ve wanted to promote an idea or argue against an idea so I would go and write a document to see if I could even formulate a reasonable argument. Could I even convince myself? Many times those articles don’t go beyond my own laptop because the data does not justify my position and I change my mind. The act of writing clarified my thinking or changed my mind and saved other people’s time.

Lastly, I write because it’s fun for me. I like to think I’ve grown over time but having a written record actually helps me see the change. I can look back at all the silly things I used to think or I can look back at a past project and see how I’ve grown (or not).

Writing Tips

I’m still learning and practicing my writing so I’m not sure how helpful my tips are. I have picked up a few things, over the years, that I keep in mind as I write. Maybe a few of these will help you too:

• Be kind to your reader. What do they want to know? What do they already know? What do you want to communicate? Make your writing easy for your reader.
• Read your writing out loud. You will notice so many mistakes and missing words that you do not catch by reading silently.
• Put key information up front. For example, when writing a paragraph, the first sentence should say the key idea of the paragraph. Ideally, the first words of that sentence will say it. Your reader will skim through your document so if they can get all your main points by reading the first few words of each paragraph then you win. If your reader cares how you came to your conclusions, they can read the rest of what you wrote. Did you notice I used this technique on this article?
• Use simple words and phrases where possible. Shorter is, almost always, better.
• Avoid “weasel words” or vague terms.
• Use absolute dates and numbers and be precise. Saying “10 years ago” forces the reader to do math while saying “2015” is both concise and easy on your reader. Saying “20% faster” may sound good but it leaves a lot of questions for reader. 20% of what? If you write that you made a daily job run in 4ms (down from 5ms) then I can see that 20% is not very meaningful at all. Saving 20% of GPU time in a video game however can be a huge impact.
• Related to the above, avoid telling the reader how to interpret the numbers. Don’t embellish a result or say a result is good or bad. Present the data in a neutral way and let the reader form their own conclusions.
• Practice. Like most skills, you will improve by practice and thinking critically about what you’re doing.