Coding like a journalist
Tips and tricks from my years as an editor & producer
One year ago, I was working as a digital producer for a television station, spending my nights and weekends coding for fun. Since then, I decided to move into software engineering full time, and it was the best decision I’ve ever made. But I’ve been thinking a lot about what I left behind and what I took with me — skills that I honed over five or ten years of work. I know the running jokes about English majors, (and if you want to talk about the state of modern journalism, let’s get a beer one day) but I still believe that strong writing and communication skills can really improve everyone’s experience at work.
Strong writing skills are especially meaningful when it comes to technical documentation. Good documentation can draw people in, help them understand where they’re going, and share the sense of excitement that you, the writer, feel about your subject matter. With that in mind, here are a few notes I’ve taken as a journalist and producer, over the years, that have helped me communicate in the clearest way possible.
Full disclaimer here: I’m not a technical writer. I’m not even a journalist or a producer anymore. There are amazingly talented people who have dedicated their careers to this important skill — this article isn’t meant to be an official or exhaustive record of good writing; it’s just a few tips & tricks I’ve kept track of over the years.
Find the thread
What’s the core concept of your article or documentation? Why are you spending your valuable time writing? Put together an outline — they are so effective and are often overlooked. If you have more than five main points, you should probably narrow the scope of what you’re trying to cover. In those cases, ask yourself if you can simplify. Normally you can. If you really, really can’t, break it down into more than one document.
Answer the five big questions
- Who is your audience? Write directly for them.
- What do you want your readers to remember after reading your article?
- Where is this going to be used? Keep context in mind — what kinds of things do (and don’t) your readers already know?
- When is this information important? Some of your readers might not need every single detail — again, keep context in mind, and explain the situations when your library, language, or topic is most meaningful.
- Why? Why does any of this matter? We’re all just floating on a rock that’s orbiting the sun, and the heat death of the universe is imminent … In all seriousness though, give your readers a good understanding of why you’re writing. What got you excited enough to spend an hour writing a blog post or technical documentation?
Connect the dots
Once you have your outline, connect the main ideas with transitions. Remember to keep it simple: does idea A point to idea B seamlessly? Do you bounce between points A and B and then go to points C and D just to circle back to point B? Simplify things and really spell it out for your reader. Connections between thoughts might seem natural to you, but might not be immediately obvious to readers.
Create a narrative
Even if you’re writing technical documentation, having a strong narrative is important. Make sure to have a clear beginning, middle and end. Imagine a bell curve that starts small, gets bigger, and then tapers off. Then, imagine a witty Dilbert comic (that I don’t have copyrights for) referencing bell curves, cubicles, and unfair median vs. mean comparisons. It should make this whole paragraph funny and down-to-earth. Writing with a nice bell curve in mind will help a reader dive in, gain momentum, stay focused for the meaty, important bits, and leave understanding the main takeaways.
Use repetition and rhythm to your advantage
If you’ve got a particularly important point or a series of closely related ideas, don’t be afraid to use bullet points or repetition. Just make sure to stay on track — it’s easy to mix metaphors, jump from one idea to another, or repeat yourself unnecessarily. Once you’ve laid out any nice literary tricks you want to use, be sure to read everything through and make sure it flows seamlessly and makes sense.
Find a style guide that you like and lean in
I spent years becoming best friends with my AP Stylebook and The Chicago Manual of Style. I’m not a technical writer, so I’m sure there are a ton of good resources specifically for this type of writing that I’m unfamiliar with. Whichever guide you go with, use it as your sounding board. If you ever have a doubt or a question, defer to the guide.
Don’t be afraid to be human
You’re a human. Your readers are human. We’re all paddling this crazy canoe together, so don’t be afraid to talk to your readers normally. If you need a starting point, write the way you would speak, and edit from there. Now, there’s no need to exaggerate or fabricate data — don’t go full kayak—but documentation that’s too technical, dry, or complex will lose and confuse your readers.
Get rid of anything you don’t need
This is my last point, but it’s arguably the most important. Be ruthless when you edit. If a paragraph, a sentence or even a single word isn’t directly contributing to your main point, lose it! If you’re using repetition or rhythm, make sure what you’re repeating is worth repeating. If you’re using an example, story or visual, make sure it connects your dots or contributes to the narrative arc of your document. If it detracts, distracts or complicates what you’re trying to say at all, it’s got to go.
That’s all I’ve got, folks — I hope that these small reminders help you enjoy writing documentation more (or at least hate it less). Happy editing!
Cat tax:
