Writing == Coding
There’s more similarities between writing prose and writing code than you might expect. As a technical writer with a foot in both the engineering and editorial worlds, I spend a lot of time turning lines of code into plain English, whether it’s for documentation or blogs. And because I love helping developers share and communicate their brilliant work, I thought it would be fun to illustrate some parallels between writing code and prose.
When you’re next facing a blank screen, unsure of what to write, I’ve found there are three aspects of writing great code that are equally applicable to expressing your technical solutions in prose.
- Solid Planning
- Stick to One Style
- Elegance is Everything
Solid Planning
I’m a huge fan of planning, because it makes my life easier. I remember my first SQL project – and before you ask, yes, it was utterly traumatic – I had to create a restaurant booking system. Sounds simple, right? And to my 17-year-old mind, it was simple. You get a table for 2-3 hours and then the table goes back into the system to be rebooked…
Databases don’t work like a human brain and it was a baptism of fire trying to struggle through puzzles like “well, what if the booking requires a table for six people – oh lord, I only have tables that seat four or two. That means I need to find a table for four and a table for two close to each other, that can be joined to accommodate six, at the same time…”
In the end, planning saved me. I liberated a stack of blank A4 sheets from the printer and, using copious stick-figures and scribbles, wrote down every possible dining situation. Once I began working through the logic of each scenario, things fell more easily into place.
Strangely, I hadn’t already drawn the parallel to my English course, where I always spent 10-15 minutes creating plans for how I was going to shape my essays using jumbled spidergrams (or ‘mind maps’, as my American friends like to call them). My spidergrams today are sans stick-figures, but I still type rough quotations and drop in tons of links to material I need to refer to.
In both coding and writing, planning forces you to deeply consider your end user or audience, and make sure that you’re creating something that is going to be both useful and usable.
Stick to One Style
Programming languages are as rich and dynamic as the English language – it’s entirely possible to express the same thing in many different ways, like colour vs color. And this is why sticking to a single style is so important because consistency breeds trust – your audience and your users know what to expect from you.
I highly recommend using AP Style if you’re writing blogs, presentations etc. but if you’re writing documentation, check out Google’s Technical Writing Resources for some outstanding specific technical style guides. The style guide you choose doesn’t really matter – it’s more important that you pick one and stick to it.
Elegance is Everything
There’s a stark difference between code that works, code that’s production-ready and code that’s truly elegant. In exactly the same way, there’s a stark difference between junior-school essays, solid technical documentation and Pulitzer-winning writing.
In all scenarios, everything runs – the program does what it says on the packet, whether or not it’s a complete mess under the hood. Just like the junior school essay gets you a passing grade, even if it’s not going to win any prizes.
What’s more important is that we recognise elegance when we see it, and strive to make our work more elegant through trial, error and practice. Just like in code, elegance is hard to define but easy to see. Elegant writing is imminently accessible, engaging, efficient, and does what it sets out to do. It’s clean.
When it comes time to write your documentation, or explain your project in an article, find ways that you can express yourself in the most elegant way possible to take your audience on a smooth and engaging journey – stick to one style, write actively and remember to kill your darlings.
Engineering and writing sound worlds apart, but there are so many ways that they are similar. So when you’re next staring at a blank screen worrying about what to write, remeber – if you’ve written the code, you’re well on your way with the prose.