Non-Writers

Did you know that there was a time when people actually read release notes? Not all people read them, but some regular customers did.

Since I became an iPhone user, I’ve started noticing the release notes for updated versions of iPhone apps. The only major software publisher that consistly explains what’s new in a release is… Apple itself.

• Streamlined in-app notifications informing you when a person joins a collaborative document for the first time
• Preserve file format and full quality when adding HEIC photos taken on iPhone or iPad
• On iPad, press and hold the Command key on a connected keyboard to select noncontiguous words, sentences, or paragraphs using a trackpad or mouse

It’s not new that the release notes are an afterthought. Too often, they are written by the developer who has been given the responsibility for actually submitting the software for distribution.

During the course of a career lasting over 20 years, would you care to guess how many times I have been given data from a software developer that later turned out not to be correct?

A maximum of three.

Once, another developer informed me that something I had written wasn’t true. I provided the developer with a copy of the e-mail in which a different developer had said it was true. (No, I didn’t rat out the original developer by providing their name.) The developer demonstrated to me that it could not possibly be true. So I changed the docs.

Writing requires that you try to reach your reader. Technical writing doubly so. And that’s the part that isn’t easy. There are obstacles, and you have to do the work of overcoming all of them all of the time. Simultaneously.

Here are five of my rules for technical writers.

1. You have to understand your topic.

   In a lot of life, in conversations and in writing, you can have a vague idea of how something works. (For example, you can put gasoline in a car without understanding how the gas fuels an engine.) That’s not true in technical writing. You cannot explain what you do not understand. You have to know exactly what the ideas are, and what all the words mean. Although you don’t have time to become a subject matter expert in everything you write about, you must invest the time and brain-strain to become a student of the subject. And you must resist the seductive pleadings from non-writers to just clean up the writing of someone who does understand the topic. You’re not there to give a polish to writing that you do not understand. You’re there to explain. You have to take that commitment seriously.

   [Read More]