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.

In her last comment, Kaylene asked me if I ever get discouraged about the whole "no one reads documentation anyway!" issue. I typed out this long response, then decided it needed its own separate entry.

===

The joke around here is that no one reads the manuals unless they're bored while on hold with phone support :-) I don't really get discouraged about this issue because the products I write about are interesting enough to motivate me personally, and because whether or not anyone reads what I write, I know it's there in case a customer needs it.

In the case of some more complicated features I'm currently writing, I've had developers come up to me and say "I didn't understand what this feature was about or how it worked, but I read your user manual chapter, and now I get it." So there's some small comfort for me in that aspect :-)

Funny story, tying the iPod and tech writing together: this past weekend I bought a slightly-used iPod mini from a guy on craigslist. He advertised it as being in the original packaging, and lo and behold, the user manual was completely sealed in its original plastic. I joked with him, "it's guys like you us tech writers hate!" But I know it's just because the thing is so easy to use that detailed documentation is unnecessary. The menu items and such on the iPod are so self-explanatory that Apple could probably get away without shipping an iPod manual; but that looks unprofessional from a marketing/brand standpoint, so I doubt that'll ever happen. At my last job, I spent a couple months overhauling the manual and packaging the user received with their computer. We tried hard to make a lasting impact with a "professional" presentation, even though the information inside is as simple as "Plug the blue monitor cable into the blue video port on the back of the computer."

I do read user manuals and instructions sometimes; it just depends on the product. For instance, I had to read my coffee maker's user manual to find out how to brew at a specific time in the morning. Does that suggest an unintuitive user interface? Probably; I never would have figured the steps out on my own by just looking at the buttons on the front. So the issue might be, is the user aware that they don't know everything about the product? Is their personality type the kind to admit they aren't smart enough to figure out which functions do what and which buttons go where? I suppose these more "modest" types of people might be more inclined to leaf through the user manual (or page through the online help).

I recently bought Jade Empire for the Xbox and looked through the user manual while waiting through the incredibly long loading screens. The combat system in the game is confusing at first, and though the manual didn't provide all the information I need (I'm a "big picture" person, a viewpoint which seems to be rarely presented in the documentation I come across), it helped me understand what I was seeing onscreen so that I could figure the system out after a little while.

However, for something like a computer part (optical drive, video card, etc) I definitely don't read the manual. That's only because I've been installing computer parts for several years and don't need a manual to tell me what I already know :-) And I have not broken the seal on the iPod's documentation; I doubt I ever will :-)

It's interesting documenting a programming language though, because our end users are using our products to make other products. So we're really the middleman. A large part of our documentation comes in the form of function reference: we detail the purpose of each function as well as the relevant arguments and data types. Coming from a CS background, I know this information is extremely helpful, especially because the majority of the programming done out there is not original design, but simply maintaining and updating existing software. In these situations, function reference is invaluable, and I would hope that no one would call tech support just to figure out how a particular parameter affects the function. Then again, you never know :-)

Another reason I don't get discouraged is because I know there are some people out there who do read the documentation. I know this because we get comments on the documentation when people get stuck trying to work something out. Of course the comments are usually about incorrect or unclear information, but that's just because the motivation to say "Good documentation, guys!" is not as strong as the motivation so say "Hey, this documentation sucks!"

However, I don't expect someone to sit down and read the user manual cover to cover. Especially not an online user manual. This expectation factors hugely into the way I organize and design the help system for the Control & Sim products. For example, we rely a lot upon the "Search" and "Index" features of HTMLHelp. If we don't organize and test these systems properly, we're reducing the usability of the help system. We do a lot of internal testing, and we sometimes test actual users, but we can always do more in that respect. The fact that we're expected to participate and drive this organization and testing is just one reason I enjoy working here :-)

Today I am trying to track down a naming issue. Microsoft doesn't brand Visual C++ with version numbers anymore; they stopped doing that after VC++ 6.0 (which I used as a CS student for the semester and-a-half I was one). They switched to the .NET 200x nomenclature. So in updating documentation from that ancient period of VC++ version numbers, I'm trying to obtain a one-to-one mapping of "7.x" versions to ".NET 200x" versions. I've been bugging a couple developers here, including Brian, but if anyone out there has a solid answer for me, drop me a comment down below and we'll talk.

I'm pretty excited about several of my documents shipping, because I've been working on them since late January. Of course, I'm experiencing so-called "feature creep" as developers work in last-minute changes to the code. Some of these changes affect the documention I've already had reviewed, so I have to get some portions reviewed again. In the case of completely new features, I just make sure that the developer and my lead writer see the new/changed content once.

NI matches charity donations up to $1000 per person per year. Obviously, everyone is busy collecting money for Katrina relief efforts. I've done my own fundraising drive and will end up with something close to the limit that I'll pass on to the Red Cross.

I realize this entry is rather boring; hopefully I'll have some fun stuff to talk about once I have more free time to post, e.g., after my documentation ships :-)

In the meantime, I'll post links to this 1/2 TB hard drive. Half a terabyte?! The hard drive in my first computer was 540 megabytes. I feel lucky to have witnessed those days :-) Of course, my dad was there when computers had no hard drives at all. Scary thought! I wonder who the first person was to say "Hey, maybe people want to store more than a few kilobytes of information after they turn off the computer." Non-volatile storage - what a genius :-) Anyway, with 4 IDE ports and numerous SATA ports per motherboard, storage is becoming virtually (hah) limitless. But I'm sure people said that back in the good ol' days of the 5.25" floppy ...

I'll post one more link to one of Apple's newest gizmos. I've been putting off buying an iPod for so long now, but I think I might have finally caved in with this latest announcement ...