wheeze flan: The Three Basic Elements of Technical Communication

You are here: Home ? Blogroll ? The Three Basic Elements of Technical Communication

When clients tell me that they can write their own user manuals because, after all, they say, they already know how to write, I?m reminded of a quip from an old friend, frustrated by his software developers? inability to complete a payment application on time: ?Why does it take so long? It?s just typing.? Sadly, I sometimes think, people think the same about technical writing: It?s just typing. Which got me thinking: What does a good technical writer have to know to be a good, dare I say, great technical writer?

Understanding the Content
It?s as old as the Dead Sea Scrolls: If you don?t understand what you?re writing about, no one else will either. I have had prospective technical writers admit in an interview that they don?t have to understand the subject: ?Just tell me what to write and I can make it sound good.? These are short interviews. Of course, understanding what you?re writing about is true for any type of writing but it?s especially critical for technical writing, based on the nature of the beast. As I like to tell my new writers, very few people pick up a technical document for the pleasure of reading. Mostly, they look for the book or click on the Help button when they?re stuck and need some help immediately. So the information has to be concise, correct, easy to understand and easy to find.

Unfortunately, much of the fodder that passes for technical writing is written by well-intentioned folks who have no idea what they?re saying.

Writing Well
The reason most engineers don?t make good technical writers is because they hate to write ? some kind of right/left brain thing. It?s not that they?re incapable of writing; they simply don?t like to do it or it takes too much time for them to do it. Either way, we?re grateful that we have a legitimate way to make a living. Most times, however, the engineers are the only ones who actually understand what they?ve built and must be the source for our knowledge, our subject matter experts (SMEs). But here?s the tricky part: the process for technical writing is not just transcribing verbatim what the developers say; one must understand what?s going on and then be able to explain it in such a way that the reader ? the audience ? can understand it too. This is the hard part because engineers are often too familiar with the application to make the connections that the writer needs to explain to successfully use the item. So before the writer can start writing instructions, he has to know how the thing works, both by listening to the engineer explain what it?s supposed to do and then actually use it. Only at that point does the writer have the first-hand experience to be able to explain to someone else what to do.

Making It Look Pretty
So once we?ve figured out how the thing works and how to describe how it works, we have to make the document look good. While this task would appear to be the least important part of the technical writing package ? after all, it?s about helping people learn to use the technology, right? ? it?s actually the one that generates the most controversy. Ever look at a document and notice that the fonts for a bulleted list are the wrong size? or that the indented material is inconsistent? or some of the words in a heading are capitalized and some are not? Unfortunately, these are the types of inconsistencies that get the most attention. In our own technical writing shop, we are fortunate to always have a second pair of eyes to review and edit everything we produce. It?s very difficult to edit your own work; our internal edit process helps catch most of these inconsistencies.

Sound complicated? It?s certainly more complicated than just typing.

Tags: consulting, detail oriented, directions, documentation, instructions, technical writing, tools, Training, understanding, usability, Writing