This is an appallingly short-sighted view. Technical accuracy is indeed important, but so are presentation and style. Few engineers would listen to a job applicant who shows up in a bathrobe and slippers, or a litigation attorney who speaks like a valley girl-and yet somehow, these same engineers expect their customers to slog through pages of meandering, poorly phrased text. Even matters as fundamental as spelling, grammar and proofreading are often treated as mere annoyances-piddling details that are worth nothing more than a cursory glance.

(To my relief, I have not encountered any such attitudes at my place of employment. I hasten to say this, lest anyone think that I'm complaining about people that I work with! No, I've found that we all appreciate value of excellence, for which I am always thankful. But I digress.)

Mind you, I understand that there are times when a company might not choose to invest an all-out effort in user manual development. This can happen during early startup stages, for example, when manpower is in short supply and products are still undergoing refinement. Unfortunately, many small companies never grow past that stage. Even after many years, they continue to thinks of user documentation as a trifling detail which deserves only a modicum of effort. By perpetuating that mindset, they ultimately shortchange both customers and themselves.

Like it or not, a company's user documentation (or lack thereof) is a reflection on company itself. You can be sure that your customers will notice if user manuals are poor or non-existent. In today's busy world, where people need to absorb information as efficiently as possible, lack of quality documentation can be nothing short of disastrous.

A related problem is failure to use proper language. Consider case in which many of readers are not native English speakers—say, when marketing a product in Europe or Asia, or when writing assembly procedures for foreign-born factory workers. In such cases, it may be necessary to keep language fairly simple. If this is not possible—say, when discussing complex details that demand a great deal of precision—one can often compensate by adding some aptly-chosen charts, diagrams or photographs. Either approach can be helpful in making complex text a bit easier to absorb.

4.Not being suitably graphic

It’s undeniably cliché, but true nonetheless—a picture does paint a thousand words. Similarly, a manual that makes judicious use of images and diagrams will be much easier to understand than one that is composed entirely of text descriptions.

Some consider this to be childish and unnecessary. I don’t, and my experience has shown that majority of users appreciate having these visual guides. Remember; no matter how sophisticated your readers are, they’re still human. Even an intelligent, otherwise careful reader can accidentally miss some important detail, especially when pressed for time.

5.Not striving for excellence

It’s interesting to see how programmers and engineers can strive for excellence in many aspects of their work, yet take exact opposite approach when it comes to documentation. “Who cares about wording anyway?” I’ve heard many engineers say. “We’re not writing poetry or screenplays here. What matters is that documentation must be technically accurate.”

This is an appallingly short-sighted view. Technical accuracy is indeed important, but so are presentation and style. Few engineers would listen to a job applicant who shows up in a bathrobe and slippers, or a litigation attorney who speaks like a valley girl—and yet somehow, these same engineers expect their fellow techies (or worse, a customer!) to slog through pages of meandering, poorly phrased text. Even matters as fundamental as spelling, grammar and proofreading are often treated as mere annoyances—piddling details that are worth nothing more than a cursory glance.

(To my relief, I have not encountered any such attitudes at my place of employment. I hasten to say this, lest anyone think that I’m complaining about people that I work with! No, I’ve found that we all appreciate value of excellence, for which I am always thankful. But I digress.)

Remember: When writing for one’s fellow techies, one should bear in mind that they must often absorb voluminous amounts of information in scant amounts of time. When writing for laymen, one should make text as gentle and easy to digest as possible, lest they become lost in an ocean of geekspeak. Either way, putting a little extra effort into matters of elegance and style can make a world of difference.

I won’t go into detail about what constitutes good writing technique, as that would be beyond scope of this text. Suffice to say that a good programmer or engineer should make sure that his writing is readable and well-organized, and that it flows smoothly from one topic to another.

I would be thrilled beyond belief if I never saw another slipshod manual, or if I never heard another story about companies collapsing due to non-existent documentation. A hopeless fantasy? Maybe. Still, I hope that some techies out there will read this message, and that they’ll take it to heart.

V. Berba Velasco has repeatedly discovered the importance of good technical writing, and the pitfalls that can occur from ignoring its value.