Conference Calls Are Awesome

McLuhan famously said "The medium is the message." In my 10 months in Shanghai, I've been learning just how true that is. More than once now I've been involved in a disagreement or similar situation that has been instigated, and carried through, in email. These emails take a lot of time to write and respond to, because we all want to be precise. And because of the time difference, I don't receive emailed replies until the next day. And text-based communication removes a lot of the verbal cues you get when talking to someone.

Each time, after the emails have bounced around for a week or so, someone has suggested a conference call. These calls have cleared the air, clarified intentions, removed negative feelings, and gotten everybody on the same page and moving forward.

So as emails continue to fly between Shanghai and Austin, I've learned to listen to that first feeling of frustration in "We're not making any progress here" or "There's some incredible misunderstanding going on here". At the first hint of that, I suggest a conference call. Because of the 13- or 14-hour time difference between the branches, those calls can be painful. They involve someone staying late (or remote-desktopping into the office from home) and someone getting up early. But that's the reality of doing business in a global economy (and a global company). For me, it just means 1) an easier time catching a cab in Shanghai and 2) two cups of coffee in the morning instead of one ;-)

And the calls, as I've said, are worth it for the benefits they provide and the time they save. Emails are great for one-off questions, things that don't need a huge amount of explanation, or confirming something that everybody agrees with. But when you get into the nitty-gritty of brainstorming, resolving arguments, introducing unfamiliar concepts, or similar complexities, conference calls are invaluable.

We Use LabVIEW, Too

I'm really proud to say that I'm not only a LabVIEW technical writer -- I'm also a client! One great thing about being a technical writer at NI is the opportunity to actually USE the products we document. Okay, so I haven't gotten a chance to prototype a control system. But technical writers at NI use LabVIEW every day to improve our internal processes.

That's a pretty general statement, so I'll give you a specific example. One of the great features of LabVIEW is the Context Help system. The information you see, when you press and move the mouse over a block diagram object, is determined by three fields in the VI Properties dialog box: VI description (the actual text displayed below the connector pane image), Help path (the path to the .CHM file that contains the help topic), and Help tag (the HTML file name contained inside the .CHM file). When the last two fields are valid, the Context Help window displays a "Detailed Help" hyperlink below the VI description.

We have internally-developed tools to "populate" (import) the Context Help -- by which I mean, transfer the proper information from our source material into the VIs themselves -- before release, so all the information appears properly in the software. But (like all software) these tools aren't perfect, so we have more processes in place to verify a successful Context Help population before release.

Now, LabVIEW has a HUGE library of VIs, functions, structures, constants, and so on -- and almost every object has controls and indicators with even MORE context help. Not to mention dialog boxes, which contain even more information. I don't know exactly how many, but the core product has tons, and our add-ons add on (hah!) even more. This massive number makes it really challenging to manually verify the Context Help population before each release. And yet that's what we do -- spend a lot of time hovering over icons and clicking Detailed Help links, and filing bug reports when necessary.

Is this starting to sound familiar? I bet many of you reading this blog have procedures for manually testing your products. Wouldn't it be great if there was a way to automate these tests? Funnily enough, I work for a company that develops products to do just that ...

So what I'm in the middle of doing now is developing an automated testing system, using LabVIEW, to verify the context help integrity of any given number of VIs. You give it a top-level palette (.mnu) file, and the VI I'm writing will recurse (yes, recurse!) through all the subpalettes, build a list of items on those palettes, and verify the Context Help for each item. 

No more hovering over palette items ad infinitum. No more manual testing. You just specify a .mnu file and away the program goes. And in fact, since the path to the .mnu file is not likely to change from day to day, you can run this VI programmatically by passing in the path as part of another process. And there you have it, a fully automated test. All you do is check the report when you come in each morning. "What errors do we have today?" And you can use this information to improve the tools that actually import the context help, because you discover all the little corner cases that you missed when developing those tools.

This is just one example of internal tools development. We've developed a whole suite of them, all using LabVIEW, to verify the integrity of our HTML help files, and use them every day. Just as the software itself might build automatically every night, so do our .CHM files. And just as software autotests might run every night while you sleep, so do our .CHM tests. 

I say we really put the "technical" in technical writing.