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.