When working with or mentoring other developers, one problem I’ve noticed is that many developers can’t write to save their life. This goes beyond “poorly documented” or whether they get grammar wrong (such as when writing in a second language). The main problem is one of organizing thoughts for a purpose and communicating them to an audience. This is something that everyone struggles with sometimes.
Most organizations, readers, and even managers don’t expect perfect grammar or prose from technical people. What they, or any reader, expect is that you get your point across clearly and in a manner they can understand. Learning to do this can often be the difference between being the leaders in a development organization and the folks that get tasked with all of the dreaded maintenance code.
If you break down the writing task as follows, you’ll be better at communicating—and convincing—through your writing.
Purpose
The first step in any writing, technical or otherwise, is to think about the purpose. Generally for developers, it is something like “explain what this piece of software does and why.” Sometimes it is “persuade someone that my approach is the best one.” Out of this usually comes a general outline of the idea you are pushing.
Audience
In my day job, I write a lot of things that are aimed at different audiences—generally one of management, architects, developers, and operations people. Often, the audience is more specific than that. I might write to operations people at a retail organization, for example. The more specific the audience is and the more I’m able to speak to that audience, the better and more effective the writing will be. For most developers, the target audience is usually other developers, managers, or operations people.
Detail
Based on the purpose and the audience comes a level of detail. That level of detail varies by your purpose and your audience a great deal. For example, when I wrote a piece on clustering in machine learning for InfoWorld, I was aiming the piece at junior developers and managers, so I didn’t want to get into deep algorithmic details. However, if I had been writing to budding mathematicians and data scientists, I probably should have.
If you’re writing a piece to explain a general concept, getting deep into configuration details is probably a mistake. If you’re writing reference documentation or how-tos, you might not only include them but structure the document around them.
Tactics and process
While purpose, audience, and level of detail are the most important parts of writing, organizing the thoughts and structuring them is critical. Most people learned the five-paragraph essay format in school: an intro, three supporting paragraphs, and a conclusion. Although most professional writing will not follow the five-paragraph format, the general structure of “why should you read this and what is it about, then the most important facts and supporting details, and finally the conclusion” is part of most good writing.
There are two schools of thought on how to accomplish that. One is to “just write and edit later” and the other is to meticulously outline and then fill in the details. I use both approaches, sometimes just one and sometimes a hybrid of the two. Sometimes I outline generally what I want to say. Sometimes I just write and edit it later. Other times, I basically write the top of each paragraph and go back and add in the details.
Regardless of your approach, editing afterwards (even if you have someone else editing your work) is the most important part. As Mark Twain said, “All you have to do is cross out the wrong words.” Fortunately, these days we just hit the backspace.
Some people I’ve worked with still have a real problem with organizing their thoughts into an outline or just getting started. An approach that I’ve used with them is to get them to just talk as opposed to write. Literally just explain it—record it and then play it back and type it. It takes longer but speaking is their most practiced form of communication.
Memes and prose
Finally, consider how you’re putting something. Are the main points emphasized? Some of this is ordering, but it also is “what is the clearest way to put this?” You see this all of the time on social media or in the news. If I say “stable genius,” it immediately causes recall for anyone who reads, watches the news, or catches social media (that’s a meme). If you’re describing a concept, what is the stickiest way to explain it?
Developers often tend to be long-winded. Avoid that. Generally, memes, aphorisms, and impactful prose use shorter sentences. A good rule of thumb: Use words with the fewest syllables and use the fewest words you can to convey your meaning, without becoming cryptic or sounding unnatural.
Practice
If your lack of writing skills is keeping you back in your career, remember that practice makes perfect. Consider writing a blog (instead of just tweeting). Write your family longer emails (instead of just texting). Write up some documentation on how a piece of code works. No developer has ever been fired for writing too much documentation (even if no one reads it).
While writing may not be your favorite thing to do, developers who can write impactfully tend to advance faster than those who merely code. Doing so is mainly a matter of practice and learning to keep in mind the purpose and the audience rather than getting wrapped up in the details of the thing you’re explaining. Try what works best for you in terms of outlining, writing then editing, or even speaking and transcribing. Experiment with different sentence structures and phrases and decide what is most “sticky.” Most of all, just keep doing it until you get good.