The Perils of Technical Writing

I used to work for the top Networking company in the world, Novell, Inc.  During my tenure there as a programmer/software engineer, I had the forced opportunity to do a lot of technical writing.  I wrote product specifications.  I wrote multitudes of engineering paperwork.  I wrote API documentation.  I created on-line tutorials for Novell's third-party developers.  Needless to say, I did a lot of writing.

After many years at Novell, my product was sent overseas and I was a part of a massive layoff.  However, the powers that be requested that I continue to write documents, "How To's", for Novell's Developers and Partners.  They would give me requested subject matter and I would write up a tutorial, or in depth article on the subject matter.  As time went on, I started working for another company, Novell put more trust in me and would ask me to come up with my own subject matter.  I obliged.  Everything went well until I wrote an article on the myriad of programming languages that could be used to interface with Novell NetWare/Identity Manager/eDirectory.  I covered at least 25 programming languages showing how to use them to interact with the Novell products.  The problem was that I wasn't an expert in most of them (I am a C/C++/C# and Java programmer).

I was writing and providing examples for Pearl, PL/M, AWK, BASIC, PHP, and a bunch of others.  I did my best.  I provided examples that worked and interfaced with Novell's products.  The article was published on Novell's partner and developer website.  It didn't take too long before the comments started coming in.  Over 200 the day it was published.  Most were negative stating that I didn't know what I was doing with PERL, or PHP, etc., etc.  These comments were being made by programmers who use their respective languages every day.  They knew the ins and outs and accepted procedures for these languages.  I did not.  I took a lot of criticism over this article.  I bowed my head and didn't write another article for Novell.

I don't know how many negative comments came in over that one article.  I have since learned my lesson.  Creating just one sloppy, badly researched article can cast a dark shadow over hundreds of great, useful, creative articles.  As a Technical Writer, one needs to make sure that they are masters of the subject matter.  If not, you better have a contact or friend that can proof read your works before you submit them.  I still love to write, but when I do so for money, I make sure that the subject matter is correct, that I have an expert in the subject matter proof read my article for technical accuracy, and lastly, have a lay person read it to make sure it is understandable for the desired audience.

Till next time,
Bill