September 23, 2005

Perusing /. as I normally do netted me this article about how 'IT' jargon disrupts the workplace. The LabVIEW style guide we follow has a strict 'no jargon' policy. For example, we are expected to define acronyms on their first usage in a help topic or PDF manual chapter. For the Control Design & Sim documentation, I define terms like single-input single-output (SISO), multiple-input multiple-output (MIMO), linear time-invariant (LTI), and other acronyms fairly regularly. It gets a bit tedious, but the thought and concept behind the guideline is sound. We can't all be control systems designers :-)

Stepping outside of your own mind is hard to do. After writing and editing Control Design documentation for so long, I wouldn't consider LTI to be an acronym worth defining every topic. But the next person who reads the manual might be a complete newcomer, or they might come from an industry where LTI means something else entirely. So it's just become a reflex I try to engage while editing a document: did I already define that acronym in this topic/chapter?

Our style guide lists acronyms we don't have to define. These include CPU, RAM, DLL, TCP/IP, etc. These also include acronyms related to NI products like PXI, DAQ, and GPIB. For what it's worth, I think DAQ is a great acronym.

Of course, it's not just acronyms: terms like "rate-monotonic scheduling" and "positive semi-definite" occur quite frequently in the CD & Sim documentation. What's the Boltzmann constant? In these instances, it's up to a developer to tell me if the term is industry standard or not. Can we expect customers purchasing this product to be familiar with these terms? I certainly didn't know what they meant when I first heard them. Unless I hear otherwise, I'm expected to define them, which I think is a good policy. You never know who will be reading your documentation.

Change is a big reason that IT jargon confuses people so much, at least in the realm of computer hardware. If you know what a Pentium 4 is, do you know what a Pentium D is? An Athlon X2? These are more recent versions of older CPUs. These technologies change so much that as soon as you learn the difference between ISA, PCI, and AGP, you've got to throw PCI-Express x1, x4, and x16 into the mix. Not to mention IDE vs. ATAPI vs. PATA vs. SATA. The same goes for software, where people use Javascript for a couple years and then switch to another language; pure HTML is being phased out in favor of a mixture of xHTML, PHP, and CSS; not to mention XML and other formatting/programming languages. This industry is in a constant state of flux, a fact that relates nicely to the multi-tasking issue I talked about a couple months ago.

Also, I discovered that my blog is #4 on Google's Blog Search for "LabVIEW." Joel Sumner occupies the top two spots. I guess this means people are reading our blogs! :-) I'm going to try and read and link to more technical writing blogs to get this address out to more people.

1 comment:

  1. You are getting popular. ;)

    I participate in the upkeep of my company's website and I have noticed that it is mostly in .ASP pages, to allow interaction with our many databases. All of our manuals are organized in a database with checkboxes which literally represent the ON/OFF state of the manual in relation to the item being checked. If a column is checked, the manual will appear on the page and vice versa. For example, our database contains all manuals from all languages, domestic and CE (Conformité Européenne, basically European Union). All of the English manuals are included on our regular manuals page and the checkbox is marked in this column for each. The non-English manuals are marked by the checkbox in the non-English column. All of the records in our database include Web links on our server and revision information. It is a group effort to keep our translated manuals synchronized with our English manuals. And all of this is sorted onto separate .ASP pages on the site. This is all new to me. I've been designing websites for ten years, but I am finding myself slipping further behind the curve. XHTML, DHTML, XML; I have a lot to catch up on. Necessity is forcing me to pick up the pace, though. Changing times and technology are forcing our website to evolve as we begin to move into web-based sales and online interactive presentations. I find that I miss the days of pure HTML and knowing everything there was to know.

    Here's to expanding our horizons! ;-)

    ReplyDelete