February 16, 2010

Visual Help for Visual Code

LabVIEW is a visual development language, right? That's why, many years ago, when I wrote the following about how to trim a nonlinear subsystem:

  1. Obtains the value of the State Derivatives parameter of the car model using the SIM Query Subsystem VI. The State Derivatives parameter contains car position, which is equivalent to the velocity of the car.
  2. Wires the State Derivatives parameter to the Parameters In input of the SIM Set Parameter Value VI. This VI sets the Value of car position to 60. The Parameter Type of car position is Fixed, which indicates this parameter is a condition that the SIM Trim VI must satisfy. This VI must return values of states and inputs that keep the velocity of the car at 60 mph.
  3. Wires the modified State Derivatives parameter to the State Derivatives input of the SIM Trim VI. This VI returns the Trimmed Inputs and Trimmed States parameters that the cruise-control system must use to maintain a velocity of 60 mph. This VI also returns the Trimmed Outputs and Trimmed State Derivatives parameters that the car model returns when the cruise-control system uses the values of the Trimmed States and Trimmed Inputs parameters.

I also included a screenshot:

Many studies have been done that indicate users skim documentation, not actually reading if they can help it. I know that when I look for help in an application, I do the same thing. Enter some search terms, find a page, skim to find words I'm looking for, repeat the process if I don't find anything helpful.

Well the LabVIEW Help is not really conducive to this kind of skimming -- not when we're telling you how to complete long procedures, anyway. Here's a page from the LabVIEW 8.5 help about building shared libraries. How easy is it to follow that procedure? (I'm seriously asking, I've never followed it before ;-) My gut tells me the answer is "not very" because you have to mentally translate our words into objects you click or options you select. I think screenshots of dialog boxes, with the relevant options highlighted, would be much, much easier to skim, let alone follow.

Along similar lines, when we're talking about wiring several VIs together (like the example above) we should be showing you a minimum of one screenshot: what the finished block diagram should look like. You should be able to reconstruct the entire procedure just from using that screenshot without ever looking at the text. Maybe that's unrealistic, but you should be able to get close.  Ideally we should embed all screenshots as VI snippets, as Phil points out in the comments below. Unfortunately the CHM format doesn't support dragging objects out of it, so we can't use snippets in the LabVIEW Help right now (which is kind of embarrassing, to be honest :-).

Similarly, for dialog-box heavy procedures like building a shared library, you should be able to skim our dialog box screenshots, see which options we highlight and what the settings are, and make your dialog boxes match.

The bottom line is that I feel the LabVIEW Help could use more screenshots. There are too many instances where we rely on text to describe operations can can be understood easier as screenshots. After all, we're a visual programming language, right? Yet we're not showcasing our best advantage in the help for the product itself.

As I write more LabVIEW documentation I am going to promote these ideas internally and see where they go. Maybe you'll see the results in a future version :-)