T-Rex logo

T-Rex Software and Technical Writing:

    The real problem with Technical Writing is that it's, well, too darned technical.  The phrase is meant to describe writing about technical things; somehow that implies (to some writers) that the writing has to be full of dry, "technical" terms -- and written in a style that is hard for the reader to understand.

    That just doesn't have to be true.  A well-written technical document should be easy to read and should be written using language that the student already understands.  What a concept!

    During my 20+ career in IBM, I had a management assignment where I managed a 80-person group of Technical Writers.  These people had all the pre-requisites: they had good vocabularies and understood grammar, punctuation and style thoroughly.  And, together, we created a set of standards to make the final writing understandable by our target reader.

    First, we decided that we would write using, as much as practical, a word-list from an eighth-grade vocabulary.  Aiming too low?  Not when you realize that the "eighth-grade reading level" was that of the typical high-school graduate -- in 1980!  Things have surely improved in the past 20+years -- right?  Wrong.  Recent studies indicate that high-school graduates are substantially POORER readers than those of twenty years ago.

    So, writing at an eighth-grade level was a good idea -- to make the final material readable and understandable to our target audience.  We tested for this.  And we found that even individuals with higher reading levels appreciated the eighth-grade word list and style.  After all, the purpose of technical documentation is to convey desired information.  And, as in all things, the KISS ("Keep It Simple, Stupid!") principle applies to writing, too.

    We also decided to use short sentences and to address the reader using "active" voice.  That is, "do this" as opposed to "this is done by..".

    Writing at an eighth-grade level is hard for professional writers.  They spent their entire time in school motivated by their teachers to display their vocabulary.  Writing short sentences, using active "voice" and an eighth-grade reading level word list didn't impress teachers all that much.  But that is exactly the best way to communicate with a target audience.

    Finally, we decided to write in the manner of the spoken word.  How often have you read a sentence in a book that seemed complicated and contrived?  If you read it out loud, you'd conclude that the writer would NEVER speak those words that way.  Read back over the past few paragraphs; I endeavor to write as I would "say" the words if we were face-to-face.  It's the right way.

    Our testing proved that the documents we produced with these standards had the highest rating for readability and reader comfort compared to any prior documents produced at IBM.  And these are the skills I use when doing "technical" writing.

    If you like this style, I'm your man!

    Click to contact us.