Language Writing

Putting technical back into technical writing

As a student of writing for well over 40 years, I’ve learned one thing: you can’t write about what you don’t understand.  This is true whether the topic is Shakespeare’s contemporaries (my doctoral thesis topic), what you did during your summer vacation (a topic I never assigned when I taught Comp 101), or the attributes of an SQL database (which my company has recently done).  Or perhaps a more accurate statement might be, you can write about something you don’t understand but no one will understand what you’re saying.

In the field of technical writing, I’ve discovered that people who know how to write don’t necessarily make good technical writers.  The problem is they don’t grasp the technical concepts and therefore have trouble presenting the information in a way that is actually helpful.  For what we call user-facing materials (user guides), the problem is not as bad.  Even non-technical people can figure out how to complete the fields on a screen and write about them.  (Although there’s nothing more frustrating than consulting a user guide for an explanation of field or process and find something like, “Enter the number” without the slightest suggestion as to where you’re supposed to find this “number” or what it does.  But that’s just poor writing, by a technical person or not.)

The real problem is asking a non-technical person to write real technical materials, such as functional requirements, documentation for an API, analyze a database, that sort of thing.  It’s not just that the non-technical person doesn’t know how to talk to technical people.  It’s actually the concepts.  They just don’t get it.  So what they write often doesn’t make the slightest bit of sense.

As the owner of a technical writing company, the way I’ve dealt with this problem is to hire technical people who can write.  All of my current employees have engineering degrees. While their writing skills may not be quite as strong as their technical skills, I can work with their writing to make it better.  I can’t work with someone who doesn’t understand the technology, regardless of how well they write.

Leave a Reply

Your email address will not be published. Required fields are marked *