Juha-Matti Santala
Community Builder. Dreamer. Adventurer.

Hey dev student: you should study creative writing

One of the key skills in modern worklife is the ability to communicate with other people. Communication itself is a vast field of skills but for software developers, a crucial one is the ability to write. This is becoming even more important in modern remote work life where your teammates, stakeholders, clients and partners can be all around the globe.

Over the past few years, I've been working with a lot of students through various roles: from the perspective of teaching programming, doing employer branding for a software company and from running developer communities. I've been half jokingly said often that if I could decide what to change in IT education, I'd add a compulsory creative writing class to the curriculum. As I think back to my own studies at the university, I mostly remember writing UML and ER charts and that one project course report that was half technical documentation and half academic writing. And the bachelor's and master's thesis writing that I never finished.

What do we devs write about then?

First and maybe the most obvious one that springs to mind is the code. Work life has taught me one important thing about code: we spend way more time reading the code than writing it so it's not enough that a computer can understand your code.

"Programs must be written for people to read, and only incidentally for machines to execute." - Harold Abelson

Naming your classes, functions and variables isn't just a technical exercise but a creative process where we aim to connect the real world equivalents to abstract code.

In addition the code, we write quite a lot of other stuff too: commit messages and pull request descriptions (or equivalents in your version control systems), bug reports, feature descriptions, internal process descriptions, wiki and intranet content, readme files and who knows what else. Technical in nature but creative as its aimed for a human reader nonetheless.

And to keep going, we write Slack/Teams messages, emails, comments, instructions, public documentation, meeting memos, briefs and reports.

Some developers even end up writing social media content, blog posts or newsletter content – whether as part of their job or as a hobby.

That's quite a lot of writing, given how little we spend time teaching and learning it as part of our studies.

Sell your ideas

In a perfect world, one could argue that the best idea or viewpoint always wins. We do however live in an imperfect world where there's unlimited amount of ideas and extremely limited amount of time.

When we want to win people to your side, we need to succeed in communicating our ideas clearly and in a way that is well reasoned and inspiring. It could be high level ideas like new products or features but also much more day-to-day things like the way your team operates or bringing in new libraries and technologies to a project.

By putting effort into good documentation, you make it easier for both you and your team in the long run. With a ton of experience, I can confidently say that it's way nicer to start working on a bug when you have a bug report that's well written and documented.

The things you know at the moment of writing will escape your memory faster than you think so it's crucial to write them down or you and your team will end up wondering what does it mean that the "reader doesn't work" six months down the road.

Good storytelling skills are valuable in work life. And even if you never probably end up writing poems or novels at your job as a dev, skills in language, storytelling and communication learned through creative writing  will go a long way to improve your changes at succeeding in your career.

How to get better at writing?

In addition to aforementioned creative writing classes and reading prose, I highly recommend starting a blog. I have previously written why you should be writing a blog, how blogging can be an effective refactoring tool and how writing documentation can improve you code quality.

Blogging about technical things hones your skills to tell stories, to explain technical concepts in an easy-to-understand way and to sell your ideas. As an added benefit, it builds your credibility, visibility and personal brand which can lead to better work opportunities in your career.

Another thing is to read other people's technical writing. As of today, I'm subscribed to over 120 technical blogs RSS feeds and I regularly read documentation for open source libraries and commercial products to gain understanding how to explain things better.

What comes to writing documentation, Carolyn Stransky has a great talk about Humanizing your documentation which has fantastic pointers towards writing more effective and human-centric technical content.

Write the Docs community has a ton of great resources from what tools to use and how to build documentation culture, to a vivid Slack and meetup/conference community of technical writers.


Comment by replying to this post in Mastodon.

Loading comments...

Continue discussion in Mastodon »

Syntax Error

Sign up for Syntax Error, a monthly newsletter that helps developers turn a stressful debugging situation into a joyful exploration.