Do more writing, it is thinking

A common joke of engineering is that naming things is hard. So is writing documentation, design documents, presentations, talks, or just about anything else that is not directly writing code. Obviously the common thread through all this difficulty is the writing part. And while data science isn't 100% like software engineering, and we have to make some more efforts in presenting our models and ideas, I think it is fair to say that many of us aren't excited about writing.

Today is want to encourage folks who dislike writing at work to make an attempt to tolerate it a bit more.

Writing at work tends to fulfill a lot of different functions. For example, writing can be used to make short transactional requests, like for a meeting, for some information, etc. Sometimes it's just chit-chat for social reasons, like Slack banter full of emojis. Work is full of a lot low effort, low complexity writing that isn't super difficult but takes up a lot of time. It's not writing to get excited about even amongst the most ardent of wordsmiths.

But today I'm thinking about the more complex and difficult bits of writing. Documentation, code comments, internal project summaries, post mortems, blog posts, architectural and design documents, academic papers, even polished talks and presentations. These forms of writing are about conveying complex information to someone else (maybe your future self) when you're separated by time and/or space and thus can't be there to answer questions or make clarifications. I think this type of writing is extremely valuable to the writer, often more so than the reader. It is also a type of work that is somewhat optional in our daily work lives. We can slack, procrastinate, and avoid doing such work almost indefinitely – just look at how well documented your own code or projects are.

The reason I think this type of writing is beneficial to you, the writer, is because the admittedly painful, difficult work to do the writing is a way to force you to think onto the paper. If anything, that's why the process of writing feels so tortured to begin with. It's not comfortable to have to carefully lay out your thoughts down in a way that makes sense from start to finish.

Most of the time, we believe we have a clear articulation of our thoughts. Surely, the design of our software makes tons of sense – we can practically see the intricate web of functions and algorithms in our mind. But think of the many times you've sit down to document your code and suddenly all sorts of design gaps pop out at you. Did you really intend to make that assumption? Is the algorithm supposed to work that way? Why did we design it that way instead of some other way? This effect is probably why I find myself walking away from a documentation project wanting to refactor half of my already functioning code. Taking the time to write and think things through just highlights a bunch of the shortcomings.

While explaining your code carefully in text is one immediate way to personally benefit from writing, it's certainly not the only place. A lot of my writing in this newsletter are on topics that are somehow relevant to things on my mind. They're sometimes related to problems I'm struggling through, or just things that I feel I have opinions on but haven't really sat down to explore to their logical conclusion. So I take the opportunity of having a weekly "sit down and write something" process to explore. I don't necessarily come to a final answer each time, but I always get a clearer understanding simply because I've gone through a process of writing something down, editing it down for clarity, and taking the time to explore a line of reasoning that never occurred to me before.

Things to write

Okay, hopefully I put forth a case that the act of writing is good. But just like it's really obnoxious to walk up to someone and ask them to "be funny", or hand you a piece of paper and say "draw something", I really should give some ideas of what to write.

First, explaining things that need explaining. Documentation clearly falls under this category. It also applies to how things are designed. Both of these things often change quickly and the details of which are not written down anywhere. Docs can drift away from the software it is documenting within hours or minutes being written. If you can't remember when the last time someone wrote down an explanation for why things are built the way they are, it's a good time to write some docs.

Next is laying out plans for the future. Every endeavor that over an hour is probably complex enough that it can benefit from planning. Here, you have the exercise your ability to imagine the future and the path required to get there. As you flesh those thoughts out, you're naturally going to be able to see important decisions and potential roadblocks. Just keep writing and exploring those until you reach the end.

Stories. Storytelling is an integral part of work. A lot of researcher and data scientist work involves pulling a narrative out of data and telling a convincing tale with the clues extracted from the data. You're probably already writing these things already. But if you're not, this is where you can take the opportunity to tell a story to someone in an internal talk or something.

Teaching your future self

There's an adage that the best way to learn something is to teach someone else that same thing. The act of teaching and coming up with explanations that is accessible to someone learning requires us to think a lot more ahead of time. It's often necessary to write down detailed notes and lesson plans to organize the material into something that can be digested. This is exactly the writing process we want to engage in.

But organizing your thoughts is hard enough, so I really don't recommend pressuring yourself to try writing for an actual audience unless you have to. The only audience you need for a lot of your writing is... your future self. Your code comments, notes, planning documents, design documents, a lot of these things will only be serious read by you. The occasional colleague reading any of those won't be reading nearly as carefully as you would. I'm positive that my Master's thesis fomr over 15 years ago was read by my committee, myself, and will never be read by human eyes again. Our words are often unimportant to everyone but ourselves. No point in stressing over it.

Making yourself the future audience is nice because the only person you'll offend, or embarrass with poor writing is someone who you know can be forgiving. You can explain to your future self the detailed though process you went through to make a design decision and never fear that the reader will feel you are being too pedantic. After all, you know how much you can forget.

Put all this together and the recommendation for writing more is to not set the expectation that your writing be seen by anyone you don't want to show it to. Keeping a private journal of events or thoughts is just as effective as writing public newsletters. Documenting your personal one-off scripts and checking them into a private GitHub repo is just as rewarding as checking those same docs into a big open source project.

To end, I'll mention some wisdom from another of my hobbies, photography. The trick to becoming a good photographer is hiding all your bad photos. If I try my best, only about 5% of my photos are worth showing another human, let alone saving to print out. The same goes for writing, it doesn't matter if no one ever sees any of it. The journey, the thinking, is what matters.

Standing offer: If you created something and would like me to review or share it w/ the data community — just email me by replying to the newsletter emails.

Guest posts: If you’re interested in writing something a data-related post to either show off work, share an experience, or want help coming up with a topic, please contact me. You don’t need any special credentials or credibility to do so.

"Data People Writing Stuff" webring: Welcomes anyone with a personal site/blog/newsletter/book/etc that is relevant to the data community.

About this newsletter

I’m Randy Au, Quantitative UX researcher, former data analyst, and general-purpose data and tech nerd. Counting Stuff is a weekly newsletter about the less-than-sexy aspects of data science, UX research and tech. With some excursions into other fun topics.

All photos/drawings used are taken/created by Randy unless otherwise credited.

• randyau.com — Curated archive of evergreen posts. Under re-construction thanks to *waves at everything

Supporting the newsletter

All Tuesday posts to Counting Stuff are always free. The newsletter is self hosted. Support from subscribers is what makes everything possible. If you love the content, consider doing any of the following ways to support the newsletter:

• Consider a paid subscription – the self-hosted server/email infra is 100% funded via subscriptions
• Send a one time tip (feel free to change the amount)
• Share posts you like with other people!
• Join the Approaching Significance Discord — where data folk hang out and can talk a bit about data, and a bit about everything else. Randy moderates the discord. We keep a chill vibe.
• Get merch! If shirts and stickers are more your style — There’s a survivorship bias shirt!