Announcing LabVIEW 2009

Yeah, the cat's out of the bag! We're publicly announcing LabVIEW 2009 today. If you're attending NIWeek next week, you'll of course get a more in-depth look at it, as well as a chance to pester developers about it :-)

I'm pretty excited about the Enhanced Block Diagram Cleanup feature. I used the first version of this feature a LOT in LabVIEW 8.6 when developing some VIs here for internal use. It is amazing but of course it had its limitations; those have largely been addressed in this release.

It's always a little strange seeing these feature names up on the web; they began as internal feature specifications and we've been talking about/referring to them for a long time now, haha.

These Sentences Confuse Me

From ESPN:

Jamie Moyer allowed seven baserunners before recording an out in the third inning. Somehow, none of them scored.

I read this bit and did a double-take. This makes it sound like Moyer did the following:

• Allowed seven baserunners in the third inning
• Did not record an out until the eighth batter of the inning
  
• Did not give up a run during this time
  

If you follow baseball, you might remember there are four bases. You can allow a maximum of three baserunners before the next one drives in a run. So to allow seven runners in one inning before recording an out and not allowing a run seems pretty impossible to do.

Moyer's good, but he's not that good.

(Baseball Terminology 101: We say "allowed baserunners" instead of "allowed hits" here because not all of the runners reached base on hits. The article mentions that Moyer allowed six hits in the night, so if he allowed seven baserunniners, one runner reached base on an error or a walk, neither of which count as a "hit". But you still get on base. Baseball sure does split hairs a lot.)

Continuing to read the article you'll find out that Moyer allowed two baserunners in the first inning, three in the second, and two in the third -- total of seven allowed, now -- and none of them scored. Oh, that's what the article meant -- not seven baserunners in the third inning, as implied, but seven baserunners through two and a third innings. And none of them scored.

(Baseball Terminology 101, #2: Recording one out counts as "a third" of an inning, since there are three outs per inning. So "two and a third innings" means Moyer pitched two innings and recorded one out in the third inning. And when we say "inning" here, we really mean "half an inning", since technically an inning consists of a top and bottom half, and the pitcher only pitches one of those halves. Still with me?)

So Moyer really did the following:

• Allowed seven baserunners through two and a third innings
  
• Got the requisite six outs over the first two innings (this is implied by the first bullet above, but I thought it better to state explicitly here)
  
• Did not give up a run during this time
  

Were I editing this article, I would suggest that the statements above read something like:

Jamie Moyer allowed seven baserunners through his first two and a third innings. Somehow, none of them scored.

Much clearer, I think.

Sarah Palin's Resignation Speech, Edited

I'm not trying to start anything political, but I think this is pretty interesting. This is often the end result of documents I write, although we use Adobe PDF Reader to mark comments and distribute them electronically.

I like how Vanity Fair has separate literary, research, and copy editors. Often at NI we have to combine these roles into one person.

Photo used from http://www.flickr.com/photos/nicmcphee/ / CC BY-SA 2.0

"At" vs. "On" and What it Means for the iTunes Application Store

Lonely Sandwich talking about how prepositions affect the perception of the App Store:

I could say I bought a song on iTunes, but when I speak of it like that, I think of iTunes as more of a network for content rather than an outlet, much in the same way I’d say I saw 30 Rock on NBC or heard my favorite song on my favorite radio station. So does this mean that Apple likes to think of its iTunes Stores as networks? And if the iTunes App Store is a network rather than a retail outlet, what does that make the apps it sells? And herein lies the real question: is an app a product or is it content?

Only extreme nerds think about stuff like this. Hence why I find it interesting :-)

The Rubber Duckie Test

Okay, this sounds kind of odd, but hear me out. A developer friend recently told me about the "rubber duckie" method of coding. In a nutshell, you as a software engineer place a generic rubber duckie on your desk. Every time you make a big coding decision or implementation, you explain how it all works to the rubber duckie. If you find yourself straining for an explanation, or if you find yourself unable to even come up with something logical, stop. The duckie has served its purpose -- it's helped you expose a bug or design flaw or implementation flaw that otherwise might have gone unnoticed (until later when the build breaks and it's your fault, or a customer's app crashes and you lose a $2k sale).

This is why technical writers are valuable. We are living, breathing rubber duckies, forcing you to explain your code and decisions (so that we can explain them to users) and thereby helping you uncover errors, inconsistencies, or inefficiencies in your design. And also, because we're human beings, it doesn't look like you're trying to hold a conversation with a squeaky toy.

Things You Wish We Said in Our Docs

An example of some great, actionable user feedback:

3. From the docs: "When you are ready to upload the code, select the correct serial port and NG board type on the Tools menu". This made me want to tear out my own eyes. What are the correct settings!!?

We (LabVIEW technical writers, product support engineers, applications engineers, and yes even developers) try to monitor our forums, we really do. Especially for LabVIEW Base/Full/Pro and especially during beta periods. But it's not always possible, and some things get lost in the shuffle. So we (the technical writers, now) do try to solicit your feedback directly from the help via the feedback link ("Submit feedback on this topic") at the bottom of nearly every help page. Since we introduced this link several years ago, we've received a ton of great feedback, most of which we can do something about :-)

The forums and the increase in user participation always bring up the issue of wikis and user-generated (or at least editable) docs. I'm a little swamped right now so I don't have time to discuss these issues, but rest assured I'll give them the full treatment at a later date, because that sort of stuff is really interesting to me.

But for now: what sorts of tips/tricks/tidbits/information do you wish were in the LabVIEW docs?

Hat tip to Janet Swisher for the link in the first sentence.

Error Codes

I bought a new lens for my digital SLR a couple weeks ago. As I was checking out at the store, I noticed that the staff was setting up for an instructional session of some sort. I asked them which session it was, and the clerk said it was their digital photography basics class. He said the class came about because the staff was having to answer all sorts of these basic questions and do all these quick fixes (white balance settings, etc.) for everybody. So they started giving classes so consolidate their answers into one place, so their staff wouldn't have to spend so much time answering these little one-off questions.

"Sounds similar to my job," I replied, and I explained what I do. He then said something along the lines of "Look, if you guys do one thing for your users, do this: give them human-readable error messages. I hate when I'm fiddling with something and I get error -463259 or whatever. Just tell me that the lens cap is on or the filter size is too small or something!"

I laughed because I know all to well what frustration he's talking about. After all, I use software (and other error-generating products) too :-) Luckily we pay a good bit of attention to error codes in LabVIEW. Most of the descriptions are edited by a technical writer in the same way we would edit any other piece of documentation. And for our non-native English speaking users of LabVIEW toolkits and modules, we translate the error codes into several languages, even if we don't translate the product itself. If you're frustrated with our software, there's nothing worse than trying to read error codes that are written in a language other than your native one. (Well, that's not totally true; I could think of a couple things worse than that!)

Yes, we have wonky numeric error codes, and sure there are spots where we are probably uninformative. But overall I think we do a good job of communicating why the error occurred and how you could go about solving it. Of course sometimes we can't give this information because we simply don't know it. There could be numerous causes for a particular error, and only one of them would be relevant to what you're trying to do.

What do you think about LabVIEW's error code documentation? Is it helpful to you? How could we improve it?

What's Your Bug to Writer Ratio?

Some stats on Microsoft's technical documentation for communication protocols:

1,660 identified bugs ... Nearly 800 Microsoft employees are working on the technical documentation ... More than 20,000 pages of technical documentation ...

That works out to:

• 2.075 bugs per writer
  
• 0.083 bugs per page
  

I don't know about you, but I think those are excellent ratios, even given the fuzzy numbers and imprecise information — e.g., "working on technical documentation" probably doesn't equate to "full-time technical writer". If MS dedicated an entire week to fixing these issues full-time, I bet they could resolve them all, or at least the vast majority of them. However, you just know that some of the bugs are really vague, like "Provide more information about x". Those take a long time to fix.

But the main point of the article is that MS isn't fixing documentation bugs quickly enough to satisfy the DoJ:

Lawyers for the [19 states suing Microsoft] have complained repeatedly that technical documentation issues, or TDIs, are opening faster than Microsoft can close them.

TDI?? ... That's all we need, another TLA.

Well, I'm just happy the DoJ isn't scrutinizing our docs like this :-)

Asking Questions is Key

I think one of the hardest things in technical writing, especially for new hires, is to be assigned to document a product or feature that you know nothing about. Since we have a wide variety of LabVIEW products, from signal processing to HMI to control and simulation to report generation to sound and vibration measurements (not to mention the core product itself), no one can be expected to understand the minutiae of them all. And yet our writer who works on a Control Design product might be asked to edit another writer who is working for an HMI product. Or the signal processing writer might leave and the HMI writer might be asked to fill in until we can find a replacement.

Whew. That's a lot of stuff to cover. But we're not engineers. Some of us have a technical/mathematical/scientific background, sure, but many of us are English or Tech Comm majors. How do you write help for a product you know nothing about?

Well the answer is: you learn. You do this primarily by working with Subject Matter Experts (SMEs) who, here, are the engineers who develop these products. They are the ones who have not only the domain expertise (like advanced degrees in the aforementioned disciplines), but also the LabVIEW programming knowledge to help you write documentation.

Still, it can be daunting to read a feature spec and not know where to begin. That's why I believe one of the most important skills a technical writer can have is knowing how to ask questions. (There's a reason we have several Journalism majors who work here.) Questions about functionality, background reasoning, implementation, usefulness, future features, and so on. Questions that nitpick and dig into what the developer really meant when he said "if necessary". These are all fair game in determining a starting point, an outline, for writing documentation. And once you have that outline, you're in far better shape than you were before, because you have a plan of attack. Even if you initially knew nothing about the feature.

Of course, it's a chicken-and-egg problem. You can't ask questions if you don't know enough about the feature to know what questions to ask! That's why, on the LV Doc team, we've developed a list of questions to help writers, especially new ones, get started writing about unfamiliar features. That's why research with the developers can be so valuable. Even if you don't know what they're talking about, you can pick out patterns, keywords, and things to ask questions about later.

That's why we look for writers who are geeks, who love learning technical information. We don't ask you to be a computer scientist when you join NI. But if you're going to write for (as an example) LabVIEW, you'd better get a thrill out of learning about object-oriented programming, data types, and 3D graphs. Otherwise you're going to hate it here, which is a situation nobody wants :-)

Over time you develop patterns of behavior that proves successful in giving you a sufficient amount of information about a product in a short amount of time. And then when you're asked to pitch in on another product, you aren't afraid anymore. You trust yourself to be able to obtain the knowledge you need in order to do your job well.

Tech Writing = OCD?

Over at Ars today, Erica Sadun gives thanks for the iPhone SDK's documentation:

Thank you for the kick-ass SDK documentation. I know you have employed many OCD victims who would otherwise be wandering the street picking up litter and tidying our world and instead aimed them at creating precise and glorious help pages. Sure, it takes about five years to download each API update but oh, the beauty of it when it finally is installed!

I've often had a similar thought about my team. The LabVIEW Documentation team consists of some of the most detail-oriented people you will ever meet. We debate using "attend" vs. "participate in". We agonize over "both" vs. "either". We spend half an hour brainstorming the placement of a level 2 heading and worry over its effects on the help file table of contents. We nitpick over parallelism in bulleted lists, consistent descriptions of everything, and so many other things. We pester developers with questions, trying to nail down that one perfect way of describing a feature.

And the worst part about it is -- we like it :-) (Well, at least I do.)

I don't know if it qualifies as OCD, but I'm sure there's some sort of term for how we are. "Grammar Nazi" comes to mind, but that's really pejorative and, to me, relates to Web forums where you're correcting the grammar of strangers in a situation where that activity is not expected or encouraged. "Anal-retentive" could be another description, but again, that feels pejorative :-) "Detail-oriented" is good, I suppose. I would say that we just care a lot about presenting information in the most helpful, unambiguous way possible.

Ahh, see, I'm doing it again!

Apple Releases Sept 2008 Style Guide

Hat tip to Daring Fireball (an excellent blog that I read despite not owning any Apple products) for the news that Apple has released its 2008 style guide.

When 1,000 writers are writing technical documentation for 2,000 products, consistency is very important, even down to the correct capitalization and noun strings used to refer to specific parts of software or hardware. Style guides keep everyone on the same page, so to speak, and help reduce confusion among customers when they read about "front panel objects" versus "front panel controls" versus "front panel nodes". Are those the same thing or are they different things? You, as the customer, should not ever have to wonder about this. The style guide helps mitigate these issues.

Of course this means that, as a writer, your range of expression is restricted. You cannot write everything the way you want to. There is very little room for creativity and personal style. You must submit to the whims of the company style guide. Some people find this situation constricting and frustrating. So it's important that technical writers have a say in how their style guide is constructed. It must not be an authoritative top-down mandate from on high. It must not change every two weeks at the whims of a tyrannical editor who decides that it's okay to split infinitives in January but not in March.

No, the style guide must be collaboratively constructed and able to be modified by anybody. If you have 1,000 writers in the company, you can introduce some representation into the process to make things easier; that's fine. Form a style guide committee comprised of members from different groups. Regularly rotate through representatives. Non-reps can submit their own issues (as bug reports) to the committee and argue for them in front of the committee, who will decide. Yes it sounds very, well, Congressional. And it takes a lot longer than simply deciding things. But style guides shouldn't change too often anyway -- that's one way to confuse and frustrate people. And if you're going to enforce a process on somebody, at least give them a say in how that process is constructed. You don't have to agree with their suggestions, but you do need to give them an avenue for dissent. Otherwise, all the little frustrations will build up, and the only opportunity to release those frustrations will be to quit (or move into Marketing!).

After all, you hired smart people, right? So put their intelligence to use.

And by all means, encourage new hires to look at the style guide. They will find all those weird little issues and inconsistencies that you never noticed because you've been dealing with the same document for six years.

Finally, remember that there's a reason it's called a style guide and not a style rulebook. There will be situations in which it makes more sense to go against one of the guidelines rather than blindly following the style guide. Recognize these situations and learn to make your case for why, in this case, splitting an infinitive is okay. Remember that the number one decider of any situation is "will this help the customer understand what we're talking about?"

Note here that I'm talking about style guides for technical writers. But my ideas could just as easily apply to coding conventions or "best practices" documents for programmers.

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.

What We Do

One of the tech writers here at NI Shanghai has posted a great entry describing what she does all day. Now, we don't do all of this stuff every day. But a large majority of it will be done over the course of a week or so. At any rate, it's a great peek into just what life is like at the office -- because I know you all were curious about exactly that :-)

No English Spoken Here

I've never had the opportunity to learn a foreign language before, outside of the pidgin-Spanish I can remember from 7th-8th grade. Coming to Shanghai and attempting to learn Mandarin has been an adventure. A frustrating and difficult adventure, but a worthwhile and rewarding one also.

At the same time as I'm trying to learn a new language (or at least get some basic handle on it), I'm reviewing the documentation of newer writers here. After three years, NI and LabVIEW style, as well as general best practices for technical writing that we employ, are pretty much second nature to me. So it is refreshing to have to think about our style guides in terms of new writers: having to explain and document things that I have not thought about, at a detailed level, for at least a little while. I imagine it's a similar feeling to the feeling my Chinese colleagues have when I ask them questions about Mandarin -- at least, I hope it is :-)

This experience has taught me one other thing: we do not write English at NI. What we write is an ultra-specific and precise dialect that I haven't thought up a funny name for yet (but I'm working on it). This means that the English you practiced in college, on essays and exams and in emails to your professors, will not suffice. We have our own highly-specific ways of writing and editing documentation. Suddenly you're presented with new symbols, words, terms, and rules in which those objects can, cannot, and must be combined.

I experienced this over three years ago when I first started at NI. I like to think I had a decent command of grammar coming out of college -- but in terms of NInese, I was unaware of just how little I knew. No split infinitives? Where do I put the "only" in this sentence? I have to repeat this edit in how many places? Why is there colon here, but not there? You mean we can't we say "drop"?

Learning these new symbols and patterns of communication was, just like starting to learn a foreign language, very frustrating. And this is on top of the actual technologies I was expected to write about, which required their own set of learning curves. And of course there's the processes that surround our documentation - sending documents to review, using Perforce and LabVIEW, and so on. (Look what NI has done to me -- I almost never write 'etc.' anymore, even in non-work writing situations.) Of course there's a reason for (almost) every decision and item in the style guide and the practices we follow. But figuring these out was a steep learning curve. Starting to learn Chinese must have triggered these same reactions in my brain, because it is only now that I made the connection between learning a foreign language and starting fresh at NI.

To be fair, we're up front with all this. We tell job candidates and new employees that the learning curve is high and it will take quite awhile before they feel comfortable here. We don't expect anyone to grasp all our intricacies on the first day, or even in the first month. But I wonder if we should tell them that their English is only partially useful here -- to succeed, they will need to learn a new language.

Non-trivial Typos

From now on, I'm going to start filing typos as bug reports that are far more serious than "trivial".

Barry Bonds seized on a pair of typos, complaining in court papers Thursday that the government's mistakes could compromise his chances for a fair trial. The typographical errors showed up in a recent filing by prosecutors wrongly accusing Bonds of flunking a drug test in 2001. They later admitted they instead meant 2000.

Bonds now is seeking to dismiss his perjury case based solely on the existence of this typo. Just think about that the next time somebody files you a bug report to fix a typo :-)

Digital Reviewing

For the 3+ years I've been at NI, I have been reviewing documents by printing out hard copies and distributing them to reviewers. However, now that I am doing more reviewing than writing, I've fallen in love with the commenting features of Adobe Reader. The process works like this:

1. Create CHM or PDF files.
   
2. Print CHM file to a PDF file. We can do this because we have Acrobat installed.
3. Enable PDF for commenting in Adobe Reader, so developers who do not have Acrobat can enter comments.
4. Initiate review.

In my eyes, using Adobe Reader for reviewing has the following advantages over using printed material.

• Reviews take up hard drive space instead of desk space. I have much more of the former than the latter, so this arrangement makes sense. I'd also wager that disk space is cheaper and more environmentally-friendly than desk space.
  
• I can archive reviews digitally by using source control instead of in a box under my desk. Boxes take up space and are heavy. As the company grows and we move desks, I don't have to lug around boxes of old documentation. They're all available for me on the server.
• Similarly, when I return to Austin from Shanghai, I'll have instant access to all my old reviews without involving FedEx or DHL.
  
• While I'm here in Shanghai, I can pass documents to reviewers/writers in Austin just as easily as I can pass documents to people in Mumbai, Cleveland, or any of our other offices.
• Electronic reviewing enables me to write pages and pages of edits (theoretically) under a tiny little note icon. This way if I have a long or detailed comment, I don't run out of room on the page, my comments don't jam together, and I avoid writing sideways or upside-down or things like that. Also, I type much faster and more efficiently than I write. And no one has to struggle to read my typing like they might have to do with my handwriting.
  
• If the reviewer/writer disagrees with an edit I made, they can state their reasons why in the comment itself. In this way we can have a sort of conversation about the edit itself. This conversation takes up no more space than the note icon itself, even though the discussion could theoretically be pages long. And the discussion is archived along with the PDF itself.
• Reviewers/writers can mark edits as Completed or Rejected. Similar to a bug-tracking database, actually. I then can print out (in either hard-copy or PDF form) an easy-to-read list of the edits I made and the writers' replies to these edits. This view also lets me see which edits the writer may have missed in their pass through the document. (It would be helpful to have some sort of function/command that immediately highlighted all reviews that didn't have a reply.)
• I can highlight important comments by altering the color and/or opacity of the marker. So I've developed a color-coded system for which edits are normal priority, which ones are really important, which ones are left-over from the last review, etc.
• If I need to work from home, I don't have to worry about printing out a review copy and taking it with me. I can just VPN into the office and continue reviewing normally.
  

The only limitations I could see are if I wanted to draw a figure, such as an equation, graph, or chart, directly onto the document. I don't know how I could do that without attaching a .JPG or something like that. But so far I haven't run across this situation. The Drawing tools have been sufficient. I wonder if there's a way to attach image files to a PDF or something like that.

It also might be helpful to have a mode where you could edit the PDF directly, along the lines of MS Word's "Track Changes" feature. There may be a way to do this that I haven't yet discovered. But in our reviewing model at NI, we don't do that too much.

Kudos to Adobe for making the commenting feature not only robust, but also available in their free Reader program.

From a Distance

(Side note: Every time I see the acronym for Subject Matter Expert, I think of Smee from Captain Hook. Every time.)

Through a co-worker's blog, I came across a post about sitting near your SME at the office. I cannot agree more emphatically. At NI, most of technical writers sit in the same general location as the engineers for whom they write documentation. For most of my three years here, I could swivel my chair 360 degrees and have a direct line of sight to all of my engineers.

I strongly believe that this proximity is key to establishing quality documentation. When the barrier to interaction is low, you are more likely to ask SMEs questions. If you have follow-up questions, you don't have to wait for these follow-ups to percolate through the developer's email inbox -- you can walk over to their cube and have a discussion. The developers are more likely to take your presence and schedule into account - meaning, if the release date slips or if they decide to add six new features, it's easier for them to inform you in person (where, again, you can ask follow-up questions on the spot). Because they don't have to work as hard to tell you about these changes, they're more likely to tell you. You're also more likely to socialize casually in the office, an action that improves interpersonal communication in general.

Phones and email and instant messaging are wonderful and great ways to assist technical writers. But oftentimes there's no substitute for face-to-face communication. Especially not when you're trying to ascertain the finer points of model predictive control :-)

So for all of my time at NI, I've enjoyed these benefits. This situation changed last year when I wrote the documentation for MATRIXx 8.0. During that project, I had to be aware of a small time-zone difference when calling and emailing my engineers. This was only a problem early in the morning and at lunch :-) To ease the pain, we had numerous conference calls, and in 2006 I even spent two weeks at their office so I could better understand the product during its development.

But at least my developers were in the office at the same time I was. This situation changed even more drastically when I begun working with developers in other countries. At this point you're introduced to the fascinating world of late-night (or early-morning) conference calls, reviewing & commenting on documents electronically, and never actually meeting the people you're working with. Add in language considerations, and you have a whole other ball game.

I wouldn't say that this distance decreases the quality of the documentation. However I would say that you don't get as many chances, or you have to work extra-hard, to keep the quality of the documentation consistent with what you've been doing locally. For example, consider this situation:

I email a developer in our Shanghai office at 3 PM CST. They don't get the email until 8 PM CST (9 AM their time). At this point I'm obviously not at work. I don't get their reply until 9 AM the following morning. This email has made its round trip in 18 hours. Compare that to 2 hours or less for a typical email to someone in Austin, or even California.

This fact underscores the importance of being precise when you're corresponding remotely. What if I have follow-up questions, or need clarification, to my Chinese co-worker's reply? I send this hypothetical follow-up email at 10 AM. Then it's another 23 hours until I get all of my information.

Total time for information flow: 41 hours. That's almost two days during which I am stuck on a problem or unable to do my job. And I'm assuming here that the developer actually has time to answer my question during their workday. If not, add another 24 hours onto the cycle.

I see a couple ways to mitigate this issue. One, be as detailed and precise as possible when emailing remotely. Treat your co-worker as an audience of one. Anticipate questions they might have and answer them in advance. Two, you can stay up late or get up early so that you're both in the office at the same time. Three, and this is the most effective measure, try not to rely on remote locations for decisions or information. (I know, I know -- easier said than done!) The finer points of this solution include making every use of local resources. You could spread knowledge around so that no one person solely is dependent on any other person (we also like to call this the "hit by a bus" defense). Four, and this is the most fun measure (at least for me), travel to the remote office and spend some time there :-)

(I just realized that the above paragraph probably should be a bulleted list.)

This situation obviously isn't unique to technical writing. These intercontinental concerns happen also with software development, upper-level management decisions, and technical support. Thankfully, at least in my case, you could get some fantastic travel opportunities out of this way of working. Which is my own very subtle way of segueing into the fact that I will be living and working in Shanghai for at least the first half of 2008. I leave in one week. I look forward to posting about my international technical writing experiences :-)

It's Been Awhile ...

...but I wanted to link to two posts I saw on the User Advocacy blog:

Technical Writing in Transition: Part 1 and Part 2.

Makes for some interesting reading, I think.

Quote:

Technical writing has adapted with three fundamental changes:

1. Task-oriented writing. Instead of describing the parts of a system, we walk the user through tasks and explain technical knowledge incidentally.
2. Single-sourcing. Write-once, read many; we write in small blobs which can be reorganized for online help, web help, printed manuals or marketing.
3. Plain English/Simplified text. We describe the interface, not theory, using code-like patterns of if-then language and action sequences.

And this:

...to a public increasingly acquainted with the similarities between computer-based tasks, [writing a fantastic manual] does not provide the depth of information they need, so instead they buy third-party "power user" books to fill that need.

...

When the basics of technology are known, it is easier and cheaper to have an engineer type up notes and hire a college student to format them.

I can see how this statement applies to consumer electronics like digital cameras, MP3 players, etc. Those are situations where "the basics of technology are known." Has anyone looked at the user manual for their iPod?

However, I don't think this statement applies to LabVIEW, where the basics are not known -- except to those who've been using it for years, and even then, those people still get some surprises now and then.

So that's the key phrase -- "when the basics of technology are known." That is not always the case, especially not at a company like NI. You could argue that the "basic" of LabVIEW is dataflow programming (and possibly graphical programming also). Everything on top of that is LabVIEW-specific and needs to be explained in detail in our help system. And given that we fight for dataflow attention in a sequential world, I would say that we still need to teach people the basics of dataflow in our manuals (which we do). And that can get complicated pretty quickly.

Extend now to products like the Control Design and Simulation Module. Here the "basics" become control theory, dynamic systems, etc. These topics are the subject of graduate- and doctorate- level courses and degrees. While you could ask the engineers to educate users on these topics - with formatting assistance from a college student - the results would be geared towards graduate- and doctorate- level customers, which is not necessarily our audience. Plus, it's a well-known fact that many engineers either dislike writing or don't care that they're not good at it :-)

LV's also more complex than many software programs because it's not really a program - it's a programming language. Covering the limitless ways in which you can use LabVIEW is a, well, limitless task :-)

It's like if I were to document a toolbox full of wrenches, screwdrivers, drill bits, and such. I can tell you the purpose for each tool, what types of situations each tool are good for, and maybe give you some high-level examples. But I can't go specifically into how to use the wrench with a car, sink, light fixture, two-story house, lawnmower, etc. That would take way too much time and way too many resources, especially when you realize that I'd have to describe how every tool works with every task. But here also the manual would be incomplete, because how can I know what tasks you're going to use these tools for? Maybe you like building birdhouses, but we don't talk about that because we don't have a birdhouse expert on staff. So then you're still out of luck with just our user manual.

No, the specifics are things you have to learn by taking the groundwork in the manual and applying it to your project. Or, like the quote says, you might go out and buy a book on fixing cars, or even more niche, Using Wrenches with Cars. That's where companies like O'Reilly and Wiley come in. That's also where customers, blogs, and user forums and communities help fill in the gaps. We constantly monitor these sources of information, looking for real-world problems and successes that we can include in the documentation. By "we" I mean not only technical writers, but also engineers, salespeople, marketing, etc.

(As a side note, I think we do a great job of covering LV-based tasks in our help files. We make sure to include tons of how-to content in our docs.)

I'm sure the author of those posts didn't intend to mean that all technical writing is basic and therefore we can just outsource everything to college interns. But I thought a counter-example would be useful and informative.

Beatboxing with LV FPGA and PXI

File this one under "Coolest Things I've Ever Seen." Vineet samples himself beatboxing and singing. He can do this multiple times until he is giving himself a full backing melody.

His mic is hooked into a PXI-7831R running LabVIEW FPGA. The performance is from the NI Live Talent Show we have once a year; this one was on July 12 2007.

Watch this one to see Vineet turn it up a notch!

Try doing that with an oscilloscope!