Writing for developers

Software engineering today is fuelled by sharing and open collaboration. The internet and open source have been great catalysts of both and helped moving the industry forward at an incredible pace. For years now, platforms like StackOverflow and GitHub have been ingrained into the daily routine of many. But as sophisticated as these may be, they all depend on our ability to tell stories, explain and communicate clearly through the ancient mystery that is the written word.

This post series is a somewhat random collection of thoughts about writing. From a programmer, for programers.

The importance of writing well

When you ask software developers, everyone hates writing documentation. And manuals? Oh the drudgery! Just get them out of the way so we can go back to coding.

”Nobody reads those anyway,” is a common excuse.

Well, think about how you learned your favourite programming language. Was it by reading the code of the compiler? Probably not.

The value of programming isn’t in flipping bits, but in building something that others can use. That involves explaining how it works and possibly how you did it. Inevitably, you’ll have to write something up.

Facing the blank page can be difficult, but if you look carefully, writing isn’t that far away from programming.

TDD for writing

You’ve probably heard about test-driven development and the Red-Green-Refactor mantra that Kent Beck wrote about in the early 2000s.

His advice to programmers is to break down programming into three stages. First, to figure out what the program should look like by writing tests for it. Then to make the tests pass using the shortest way possible. And when the functionality is finally down and working, you can refactor to make it nice.

It makes a lot of sense. It’s much easier to focus on one task, instead of trying to figure out a problem and find the most appropriate structure for your code at the same time. And guess what: the same works for writing prose.

Here’s how to apply TDD to your writing process.

Red: Outline

First, you need to figure out what do you want to say. What are the main points? What is the message that your piece should put across? Maybe you’re writing a README for your open source project. You might want to explain what it does and why it is good, where to get it and how to use it.

A great way or capturing those is an outline. It can take many forms, from lists of headings to mind maps, collections of notes on napkins, cards or sticky notes. Whatever helps you to figure out what sort of information should your piece convey.

Just like a bunch of test cases, an outline will become your guide when writing and your reminder when you get stuck. In the end, you’ll be able to check whether your draft says everything you wanted it to say according to you outline.

But it doesn’t mean that everything set in stone once you’re done outlining. If you change your mind later on in the process, you simply alter your outline, just as you would fix your tests.

Green: The first draft

With a clear idea of what to say, it’s time to write the first draft. This is where many people struggle the most, trying to get everything right at once while composing the text. You could spend days going over and over a single paragraph and making it perfect. And then get frustrated and never finish.

Well, don’t do that. Instead, take your outline and extend it into a stream of prose as quickly as you can. Just write and don’t look back. No amount of disregard for structure, grammar or punctuation is too much for your first draft.

The truth is that the first draft doesn’t have to be pretty. It never is. The whole reason for it is to make your tests work. Besides, nobody will ever see your first draft, because you will refactor it before publication.

Refactor: Edit the crap out of your piece

By now, you’ve got the whole thing out of your head. If you followed your outline carefully, it has everything you wanted to say. And now is the time to edit.

This is when you go over your copy and get it in shape. Add structure, cut words and clarify your message. You can move paragraphs around, rewrite them and agonise over the words for as long as you wish. And when you get frustrated, you can hit publish and go back to coding.

To be continued

When you next need to write a bit of documentation or a tutorial, try breaking down the process into outlining, drafting and editing. It makes the task much less overwhelming. And if you can already do that for a JavaScript module, why not for a few paragraphs of copy?

This is the end for part one. The next time, we’ll take a look at some more technical things like style or structure.

Subscribe to my newsletter to be the first one to know when it comes out.