How Do You Do That Again?

We consistently get feedback from our customers that the example VIs we ship with LabVIEW are really helpful. The developers put a lot of time and effort into creating examples that demonstrate new features and show how to accomplish certain tasks using LabVIEW. In addition, the examples serve as great templates for certain common applications. For example, if you want to acquire a measurement from a DAQ device, perform some measurements and signal processing on the measurement, and display the results in a plot while simultaneously writing data to a file for later use, we ship example VIs that do just that (I think; don't quote me on that :-). So you don't have to go through the trouble of digging through our help files to figure out how to daisy-chain these VIs together. We've done the majority of the work for you.

The Control Design Toolkit is a great example of how to create, well, examples :-) We categorize all the examples into separate .llb files, one for each palette. Coincidentally (or not!) each user manual chapter corresponds to a palette. So for the upcoming release, when I was trying to find a way to highlight the examples, I simply added a canned statement to the beginning of each chapter that refers the user to a particular .llb. Because we structured the examples so well from the ground up, each example .llb maps to a chapter, and I made the connection pretty easily.

The examples serve as a great connection between the tech writer and the developers. The developers create the examples and document them by adding block diagram/front panel comments and a VI description that shows up in the Example Finder. So in this sense, the developer "owns" the example. But as a tech writer, my responsibility is to make sure the descriptions are accurate and helpful. So yesterday I just finished scrubbing all the descriptions for each example. It was a good long effort, but it pays off when customers tell us how easy it is to use the product, because all they do is open a example and go to work.

Another product I work on recently received some feedback that the examples could be even more useful if they were not so complicated. This is another issue that crops up also in documentation - how complex is too complex? In this case, a professor was teaching his students the fundamental concepts that our product demonstrates, and the shipping examples were too high-level to be of much use because there are so many functions contained in each. He suggested simpler examples, with just an input, the function, and some output. This way his students could see the operation of a particular function without the "noise" of having so many other functions and wires around.

We talked about this feedback for awhile and decided it was worth it, for the upcoming product, to develop these "basic" shipping examples to demonstrate the purpose/functionality of almost every function we ship. It'll take a bit of time to do well, but the result will be a less-intimidating product that will be of more use to everyone.

So now we have a split between 1) providing pre-written programs and 2) demonstrating how to use the product to do what you want. These requirements are not mutually exclusive, but it can be hard to design a good example for both requirements. Oftentimes, as in the case of the aforementioned product, the examples are wonderful at The Control Design examples are split into two directories: Getting Started (which has the .llb files organized by palette) and Case Studies. We want users to look in the Getting Started directory to become familiar with the concepts of the product: how to analyze a Bode plot, how to discretize a PID controller, and so on. The Case Studies are not necessarily prebuilt applications, but they take a more in-depth look at the toolkit by, say, designing a controller for a hard drive's read/write head within certain constraints.

LabVIEW includes a tool called the NI Example Finder, which you can access by launching LabVIEW and selecting Help»Find Examples from the pull-down menu. If you get stuck, try playing around with this window and seeing what you find. I bet you'll find some useful applications just sitting there, waiting to be developed. Each module and toolkit, as well as some hardware, also ships some examples with their software. Check them out and see what you come up with.

I'm taking more opportunities to suggest examples and make sure they are well-documented. In addition to example VIs, we're always looking for ways shrink the "installation-to-usage" time that measures how quickly a user can *use* the product after installing it. We've been coming up with some great ideas, some of which I hope to implement in the coming months.