Communication

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]

Development can be incredibly self-focussed. Development managers and developers share information with members of the development team, and can be positively stunned to learn that not everyone outside the team has access.

Nowhere is this more obvious than when development is complete.

• There is a belief that the development deadline is available to technical writers, and in my experience, it is not available more than 50% of the time.
• There is a stronger belief that the availability of a feature to product users is known to everyone once development is complete. That has enormous impact on technical writers because:
  • Technical writers sometimes must wait for confirmation that the product’s functionality is available before taking the step that makes documentation visible to customers.
  • Technical writers sometimes do not have access to the product that users do, and cannot check whether the functionality has been made available.

I sympathize with you if you want to believe, “Well, those are just companies that communicate poorly.” That may be so. But they are still the vast majority of companies, and I lose sympathy with you if you want to argue that they are a minority.