Musings

Well the holidays are upon us, so most of the office is empty. One product of mine is nearing the beta phase, so I've been consolidating the documentation into the installer build. What's in there now is definitely good enough for beta, and really only has a few issues. The interesting (perhaps troubling) thing is that our document review process requires certain steps to be taken after beta. This means that while the developers can front-load a lot of their work before beta (which is a good thing, don't get me wrong :-)), I have to wait until after beta to move the review process past a certain point. So in that sense it's like "hurry up and wait!" This situation makes sense though, because we don't want to get the documentation into its final stages before beta ships. We often integrate a lot of customer feedback during the beta program, as any good software company should, and a lot of that feedback changes the documentation. So our almost-final signoff phase is reserved for after beta. In this case though, there might not be that big a window between beta shipment and product shipment. So while the documentation might be in decent shape, there's still several more review processes I might have to cram into a short amount of time.

In addition to all this, work is beginning on a completely new (version 1.0) product. I've been assigned to the documentation and I'm having fun learning about what the product does and how it serves customers. Documenting a 1.0 product is an interesting challenge I've watched several other LV tech writers take. You get to be in on the ground floor, and if you're good, you're able to shape the terminology and how people think/talk about the product features. The usability feedback us tech writers provide also comes into play at this early stage, when all we have go to on are screenshots of dialog boxes and stuff like that.

This evening, I'm flying back to Maryland to visit my family. Happy new year, all!

New String Functions

In my role as part of the LabVIEW documentation team, I use LabVIEW a lot, but often not the way the typical user would. Though I have some NI hardware installed, I rarely acquire, analyze, or present a signal. I use it mainly for… string manipulation. You read right. I use LabVIEW for string manipulation – searching, splitting, and replacing text. Historically, this is not one of LabVIEW’s strengths.
My VIs have a lot of string functions, each handling some specific string manipulating operation – one that splits the string, another that splits the remaining string, one that searches the resulting string of the previous two splits, etc. Also, I’m reading files, moving files around, changing file permissions, taking strings from one file and moving it to another file IF something in the string matches something else, etc. I use a lot of For Loops and a lot of While Loops with shift registers that I get the stop condition wrong on half the time. I’m sure there are ways I could make my VIs more streamline, but I’ve been doing things the same way for so many years, I’m just sort of stuck in my LabVIEW coding ways. Right now my block diagrams look like Jackson Pollack paintings.
So, now, 8.0 is out the door (of course, I had to use 7.1 to develop tools used to document 8.0) and I’m thinking to myself, maybe it’s time to teach this old dog some new tricks. What’s 8.0 got to improve string parsing and file I/O? I was in for a very pleasant surprise.
First, there’s this function called the Match Regular Expression function. I used it the other day for the first time for real (not like when I’m writing documentation for a feature, which is when I try and come up with the most ridiculous use case I can come up with that may or may not have a correlation in the real world, just so I can understand the intricacies of the feature).
So, right away I’m using a single function to parse the data from a whole text file. No searching and splitting functions. No While Loop with shift registers that I need figure out the stop condition for; just a single function with four wires. The magic is this function uses Perl-like syntax. In fact, it talks to an open-source Perl library developed at Cornell. I know next-to-no Perl script, but within minutes I was using this function exactly as I wanted to.
Second, the File I/O VIs are no longer VIs. They’re functions – nifty polymorphic functions. I can’t tell you how many times I’ve had to replace the “Read Characters from File” VI with the Open and Read File functions because I need to work with a File I/O function that only accepts a refnum for some other reason later in my data flow. Those days are over because most of the File I/O functions accept refnums and path names.
Yes, I could try and go home and relay this epiphany to my family around the dinner table, but I’m not it would meet with much enthusiasm (especially from my kids – ages 2 years and six months). This forum seemed the best place to share my enthusiasm.

Combining Work and Fun

Being a digital music aficionado, I read Createdigitalmusic every day (several times a day, actually). I submitted a news article the other day, and what do you know, it relates to LabVIEW!

Who Writes Here

Edited 1/23/2009 by Ryan:

I'm really the only person posting to this blog now, so I've removed the information about the other people. I also updated my information.

Ryan Pollack (Staff Technical Writer)—I've been working as a technical writer/supervisor at National Instruments for over four years. Currently I design, write, and edit documentation for the LabVIEW FPGA and Real-Time Modules. I also supervise other technical writers for these products.

I graduated Virginia Tech in 2003 with a BA in Interdisciplinary Studies. I spent all of 2008 living and working in Shanghai, China. In my spare time I improve my photography skills, create electronic music, write articles for several local/national magazines, stay current on technology trends, and enjoy the wonderful city of Austin.

Context Help & Super Tooltips

In LabVIEW, we have this fun feature called Context Help. The CH window updates whenever you move the mouse cursor over an object, such as a VI, wire, dialog box component, property node, and so on. The functionality is similar to "tooltips," which appear in many programs including LabVIEW. These are the little bubbles/blurbs that appear when you move your mouse cursor over, say, the Insert Table button in MS Word.

I just read an article saying the next version of Office 12 will support extended, or "super," tooltips. The idea is to "give you the idea of what a feature is for without needing to look it up in help or in a manual," according to the head of MS's User Experience team. Traditionally, tooltips have not been very expository. They show only the name of the button. These super tooltips bring those pop-up bubbles in line with our Context Help window, which can display quite a bit of text (and even a picture of the VI).

Another interesting tidbit is the way they structure the Super Tooltip phrase. The phrase completes the sentence "This is the right feature to use if you want to ___________." Our CH phrases always start with an action verb, such as "Generates," "Calculates," "Returns," "Implements," or something along those lines. Basically it's like a present-tense version of a resume :-) I'd be interested in hearing the reasoning behind the decision to use that phrase.

Another similarity: when a super tooltip is open, a user can hit F1 too jump straight to the help system. Our CH window has this feature too; you can click a link inside the window to jump straight to the help topic for that object.

The super tooltips that lead to a dialog box will also show a picture of that dialog box. I'm not sure how useful that feature will be, but the User Experience guy claims research indicates "a lot of people identified dialog boxes by their look alone." I don't understand how that's possible; I suppose after repeated viewings this might be true, but after repeated viewings, wouldn't you already know what the dialog box is anyways? Curious.

Just another example that technical writing at NI involves not only writing, but also organizational decisions and hierarchy management. I'm eager to see how these super tooltips impact usability. You can see the original blog post from the Microsoft employee himself here.

Your name in lights ... sort of

A while back our marketing manager notified us of a blurb on Embedded.com relating to the awesomeness of the LabVIEW Simulation Module 2.0. I wanted to write something about it but got caught up in other activities (such as making sure products shipped on time :-)) I like this blurb in particular: "engineers can use the LabVIEW Simulation Module 2.0 to optimize dynamic system parameters for other design objectives such as stability or vibration reduction."

The reason why I like this blurb is pretty simple: I documented that feature from start to finish, including a new chapter in the user manual and two VIs with rather large connector panes. The information came across rather late in the development cycle (as information is sometimes wont to do), so I ended up adding the majority of content during NI Week in August. It was one of those features that I literally knew nothing about, so the developer was kind enough to write a giant Word document for me, which I then squeezed and squished into a comprehensive discussion of optimizing design parameters. I thought the end result came out rather well, and another developer agreed with me when he told me he had no idea what the feature was about until he read my user manual chapter.

Another major feature was the addition of "programmatic" linearization and trimming (programmatic referring to the fact that you drop VIs on the block diagram to accomplish this task instead of using only dialog boxes). Thus the blurb: "Engineers now can linearize complex, nonlinear systems modeled in control block-diagram form and use the intuitive LabVIEW graphical development environment for the entire development process for both simple and complex systems." This feature occupied my life for a period of several months, as I added new content to the user manual and documented the ever-changing VIs. The result is pretty useful and walks users through exactly how to use the Trim & Linearize VIs to linearize and/or trim a system model.

Another reason I like this blurb is because I not only wrote the help for these features, but also served as some QA during development. If a procedure was unintuitive or complicated, I tried my best to ask why it was that way in hopes of fixing it. I also was responsible for making sure the VI parameters were capitalized properly, that the icons were descriptive (we have an in-house graphic designer to help with that task), that dialog box buttons flow nicely and are informative, and so forth. The end result is something I can be proud of, and it's nice to see all the work I put in displayed like this.