Technical Writing

Lately I've been reading a lot more documents and blogs then usual. You have to consume a lot of information if you are going to stay ahead of the game. Spending a fair amount of time both reading and writing technical information you develop an awareness of what is going to communicate clearly and what will only confuse. Here's some thoughts I jotted down recently. This applies to technical writing, not writing as art or entertainment of course. As always YMMV.

• Be succinct.  Don't be overly verbose and stay away from flowery language. State your point in the most simple way available. If possible, use graphics or visual aids.
• Define terminology. This is especially important when using words with multiple means (e.g. service, host, message). Give the context and the definition or your message will be hard to follow.
• Explain assertions. Provide the logic and supporting materials for any claims. If the data or process followed is significant, give references to where and how more information may be obtained.
• Be specific. Use hard facts as much as possible and avoid hyperbole. Speak to your point in a dispassionate way.
• Generalize carefully. Words such as "all", "always", and "never" can be problematic, use sparingly.
• Avoid buzz words and acronyms. They tend to reduce credibility and can drop out of style suddenly. If you do use them, make sure to provide definitions with each initial use.
• Avoid cultural colloquialisms. They can be hard to communicate internationally, and will reduce impact in use.

If you have other points I should add to the list, please share.

The Power of Not

Indirection is a large part of slight of hand. In slight of mouth, you use the same types of tools to influence the listener to pay attention, or not, to concepts and ideas that you are presenting. In many circles this technique is called Negation. For example, pretend I asked you not to envision a Pink Elephant. Do not think of the Pink Elephant riding a unicycle carrying a picnic basket and a perisole.

It can be very difficult "not" to do something because negatives get processed differently in our language than they do by our neurology. In this example the word "don't" is our negative. Our unconscious mind turns the words we hear into internal experiences (sights, sounds, smells, tastes & feelings) so that we can understand them. To comply with the request "Don't think about a Pink Elephant", you first need to bring one to mind just so that you can understand what you are being asked not to think about. Of course if you didn't know what a Pink Elephant was, this phrase wouldn't have the indirection effect.

Now that you know how indirection works, how can you use this to great effect during your discussions and negotiations? Let me break down the practical application a little.

I’m not going to tell you how to get a big discount on my tapes...
The wonderful thing about freewill is that it makes us constantly sensitive to when other people are trying to impose their will on us. As free thinkers and independant spirits we have a natural resistance to being persuaded. One of the key things about using negation is that it can be used to give people permission to relax their resistance. During a negotiation with someone, suppose you were to say "I'm not going to ask you to give me a big discount, because that would be rude..."

When this transpires, a couple of interesting things happen. First, the "not" lets them relax. If I’m not going to ask them, they don’t have to resist, they give themselves permission to relax. But in addition, I've now planted the idea of the discount in their mind. So when they are processing alternatives in the negotiation, they will automagically add that as an item on the list.

Now this next section may not be relevant to some of you.

When we hear that something may not be relevant to us, it generally makes us pay extra attention. We want to understand whether it is relevant to us or not. Often it can inspire us to respond even more strongly "I'll decide what is relevant to me or not!".

So I'm not going to ask you to come back for more tips later, after all, they may not be relevant to you.