My Recommendations For Writing and Communicating Well

In software development, it’s often said that naming things is one of the two hardest things to do. I completely agree!

It’s hard to name something that makes intuitive sense to you, both now and at some time in the future (when it’s no longer in your short-term memory) — let alone to someone else who doesn’t have your knowledge of the code.

But, this concept applies equally well to communicating, such as in your code’s documentation and README file, or when writing technical tutorials and blog posts that use and promote the code.

I could go on at length about my frustrations with what I see in other people’s writing. But, I’m not perfect, and my grandfather was said to have often remarked:

If you don’t have anything good to say, perhaps, don’t say anything.

So, in that spirit, as someone who’s written, reviewed, and edited a lot of documentation and technical tutorials, here are some of my top recommendations for writing and communicating well:

• Check your spelling and grammar. I can’t state this enough. With so many supporting tools, unless you’re pretty new to the language, there really is no excuse for not proofreading and correcting your prose.
• Be consistent in your use of tense. Don’t mix and match them in a single sentence.
• Use a style guide and be consistent in how you format. That way, the reader knows when a code block is a code block, a keyboard combination, a header, and so on. Don’t confuse them by mixing and matching.
• Link to further information. Whether that’s to the project’s documentation, blog posts on the topic, or other supporting information, link to them when it makes sense to do so. That way, they can keep learning where your work ends. But, don’t overdo it either.
• Provide clear, concise, and specific instructions. While you might well be your app/code/service’s subject matter expert, your reader isn’t. They may even be hearing about it for the very first time. Remember that. Tell them what they need to do. Don’t leave them scratching their heads trying to figure it out.
• Put effort into your screenshots. Don’t just take a screenshot and dump it in your writing. Think about what is most important, meaningful, and helpful to your reader to understand a particular aspect of your application or service.
• Write for as long as you need to — but no longer. That might be 500 words. It might also be 3,000. Whatever it takes to communicate a given point properly, write for that long.
• Write (and format) your code examples for readability and consumption. Don’t get hung up on writing code that conforms to best practice or code that could be shipped to production. Write to teach or communicate a point.

There are so many more suggestions that I could provide. But these, I feel, are the most important ones. I’ll expand on each of them in future posts.

Matthew