How do I turn this thing on?

I caught the following passages over at HardOCP this morning. The quote comes from a review of the Voodoo ARIA Home Theater PC (HTPC). Although the product is a Windows-based computer, the outer case and presentation to the user is drastically different from a typical PC.

One thing that I mentioned earlier was the extreme lack of documentation on the Voodoo PC ARIA. Granted, it’s a new product for Voodoo, but we spent a small fortune on this system and I was actually scared when I first pulled it out and realized I had no idea how I was going to use this system in conjunction with my entertainment center. My perception of value had dropped significantly. Heck, my $250 Panasonic DVD player has a 100% complete manual that explains every single nuance of every single function you could possibly use.

I didn’t even have the first bit of information regarding how to use Windows Media Center Edition – so I did what any guy would do – I hooked it up and started pressing buttons.

It took me a good hour to figure out how to get a properly sized video signal to my TV, so I figured that it would be a perfect question for Voodoo to answer.

... My point of contact for anything I needed was with my sales representative, Lance. Lance and I exchanged a couple dozen emails and phone calls, many instigated by him and inquiring to how my system was doing. That calmed many of my fears about being stranded.

Lance got me in touch with their technical support department and I was quickly assisted by their knowledgeable staff in setting up the ARIA to not only interface properly with my HDTV, but to be sure that my Audigy 2 ZS was properly configured.

I also received updated documents on the ARIA’s functionality that I hope will be included in future ARIA sales – they were certainly things I would have liked to know out of the box.

The emphasis is mine. I wonder: how many users end up not finding what they want in the LabVIEW documentation and then reduce their opinion of our product? Is there anything we can do about this?

Coincidentally there is an ongoing thread on the Dev Zone about how users best learn LabVIEW. It's interesting to see some of the comments there regarding the documentation. Because we (tech writers) don't deal with customers on a daily basis, it can be a little unnerving to hear their unbiased opinions about our work! But all feedback is helpful and (given the proper resources and time) will lead to improvements. This thread is an opportunity to get some interesting data points and scenarios from actual customers, which is great. We're also working on ways to give customers a more direct way to comment on the documentation.

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.