It's Not Documentation, It's Communication

If you see documentation as just release notes, user manuals, configuration guides and so on, then you're missing the point and the power of professional writers. Any and all technical information, whether static or dynamic, needs to be shared with or communicated to a disparate community of stakeholders.  The more stakeholders, the more critical the need for trained technical writers becomes.  Think of documentation as a critical node in the routing of information, and the algorithm that controls that node as a trained writer.
 
A trained writer understands:

• Writing for different audiences;
• The difference between technical and non-technical language;
• The use of dialects (hint: never use dialects); 
• How to avoid idioms, metaphors and analogies that wouldn't be understood by non-native speakers;
• What assumptions can be made about the audience;
• When a piece of writing is ambiguous, and how to make it unambiguous;
• Why short sentences are important;
• How to avoid giving the reader "wall of text" blindness;
• When to use, and importantly when NOT to use, visual aids;
• The benefits of lists and when they're appropriate;
• Grammar, punctuation and semantics, i.e. good writing.

You might think that the expense of having professional writers is not necessarily worth it.  After all, a friend of mine who is also a professional writer commented that the quality of writing in 50 Shades of Grey was mind-bogglingly bad, and yet that series of books has sold in ridiculous numbers and inspired a film.  Not bad for an author who by all accounts really, really needed an editor.  But here's the rub: Sex sells, and in big numbers.  Technical documentation does not.  If people are reading what you write because they want to, then the quality of your writing is less important.  If people are reading what you write because they have to, then the quality of your writing will have a big impact on their understanding, and even whether they read more than a few lines at all.

Doubtless you will be aware that there is a huge difference between listening to an soporifically boring voice and listening to the aural feast of a mesmerising, majestic voice. It is the same with writing.  Read One Hundred Years of Solitude by Gabriel Garcia Marquez and rejoice in the fluid, hypnotic intonations and the depth and vibrancy of the picture he paints with mere printed letters on a page.  Then read The Most Boring Story Ever Written.  Sweet Lord, take me now so that I might suffer it no more.  You don't have to be a fan of magic realism to appreciate that Garcia Marquez injects colour and life into his writing in a way that surrounds and overwhelms your mind's eye as you see the story unfold page after page. And yet the story he tells, whilst full of symbolism and allegory, is largely one of family life.  As the The Most Boring Story Ever Written makes clear, mundane can be mundane; as Garcia Marquez makes clear, it doesn't have to be.

The same applies, although perhaps with less creative license, to technical documentation.  It is not the message that will make your documentation readable, it is the delivery of that message. The message contains the value, the delivery communicates that message.  It doesn't matter how valuable the message is if you can't deliver it in a way that your readers can consume.  That doesn't mean that your delivery method - help file, PDF, web help, popup, tooltip, annoying paper clip - isn't important, but that's the difference between driving, flying and catching the train.  Each one is better in different circumstances, but frankly as long as you take one of them and get where you need to go in a decent time frame it doesn't matter. But driving in a Range Rover is different to driving in a Russian jeep.  A professional writer will produce a written delivery that is the Range Rover of communication.  An unprofessional writer will produce something closer to a Russian jeep.


At the start of this post, I suggested thinking of documentation as a critical node in the routing of information.  But the writers who provide this documentation can be conductors who allow the information to flow freely, or they can be insulators who wrap the information in layers of obtuse and unparseable linguistic murk.  Our role as professional writers is, more than anything, to conduct the information as freely as possible.  We are not "people who type", or dull people with an insane perfectionist streak for things that no-one else cares about.  We are professional communicators who polish our words to a conductive shine so that our readers can get what they need quickly and easily.