January 11, 2007

A Guide to LabVIEW Documentation, Part 1

As part of a great effort between our technical writers and the SW developers, LabVIEW has multiple entries into the LabVIEW Help. The LabVIEW Help itself is huge, which is mostly a function (hah!) of the number of things you can do with LabVIEW. Additionally, because many LabVIEW customers use the product to make other products, we have to account for a lot of use cases, generalities, and assumptions about what people actually do with LabVIEW. (That's why we try as much as possible to get feedback from users, but that's an issue for another post entirely.)

In this next series of posts, I'm going to cover the various ways in which you can access the LabVIEW Help from inside and outside the software itself. Here's the most general way.

Start>>All Programs>>National Instruments>>Labview xx: Going here shows you three useful entries: LabVIEW Help, LabVIEW Manuals, and Readme. The first link opens lvhelp.chm, which is located in the labview\help\ directory. ( where labview is the directory to which you installed LV.)

This help file is the gateway to just about anything you could want to find in the LabVIEW Help. Starting with LabVIEW 8, the technical writers made a decision to stop splitting content into PDF and HTML source. We decided to make (nearly) every topic available from within the HTML-based LabVIEW Help. We kept a couple of PDF and printed manuals, but who knows how long those will last? (The switching process itself was large, complex, and often painful. Maybe that's a subject for another post.)

The LabVIEW Help is modular and extensible. We use Microsoft's HTMLHelp framework (and FAR to do all the work of compiling and managing settings). Every time you install a LabVIEW add-on, such as the LabVIEW Real-Time Module or the LabVIEW Simulation Interface Toolkit, another book (or, more likely, several books) appears in the LabVIEW Help's table of contents. So whether you're looking for help on an FPGA topic or for information about the Control Design Construct State-Space Model VI, the LabVIEW help is your one-stop shop.

In fact, the lvhelp.chm file itself is mostly a reference to other install .chm files. For example, in the labview\help\ directory, glang.chm contains most of the VI & function reference information. glang = G Language, get it? :-)

lvhelp.chm "includes" both of these files (and many more), so the lvhelp.chm file itself contains very little content -- mostly just the legal and high-level organization topics.

The second link takes you to the labview\manuals\ directory. If LabVIEW or an add-on installs PDF manuals, those manuals will show up in this directory. Because of the aforementioned shift to HTML-based documentation, not too many add-ons use this folder. LabVIEW itself does, and two of my products (the Control Design Toolkit and the PID Control Toolkit) still install PDF manuals here. But products like RT and FPGA produce almost no PDF documentation anymore.

PDFs come and go all the time. For example, in the Simulation Module 2.0 release, we shipped a PDF manual. For the subsequent release, Simulation Module 8.20 (the version number jumped up to be consistent with LabVIEW's), I converted the PDF into HTML (like magic!). Some other groups in NI are doing the reverse; going from HTML documentation to PDF and/or printed documentation. It's all based on what works best for the customer.

The third link is to the labview\readme\ folder. I'm pretty sure that all LV add-ons install readme.html files, and these files get placed into this folder. (Of course the files are all named differently so they don't overwrite one another.) Readmes typically contain installation instructions (because the readmes are visible on the top level of the installation CD), information about new features, bug fixes from previous versions, last-minute documentation updates, and known issues with the current version. However, the presence or absence of this information differs from product to product, even among LabVIEW and its add-ons. In addition, some developers prefer to write their own readmes, whereas some prefer to hand off the readmes to us technical writers.

No comments:

Post a Comment