- 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.
- 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.
- 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 :-)
Why should we need to reconstruct it? Maybe the example could be included in the help as a VI snippet.
ReplyDeletehttp://zone.ni.com/devzone/cda/tut/p/id/9330
Good point Phil. I was going to address that issue. Unfortunately the CHM format we use to deliver help doesn't support dragging anything out of it, so we can't use this awesome feature at the moment.
ReplyDeletePerhaps NI needs to transition to HTML based help, where you can also incorporate things like Flash animation for more complicated issues.
ReplyDeleteThis should also make it easier to connect the system to the online help, so that if you want something that's not available locally (examples, videos, tutorials, etc.), you just click the link from the page you're already in.
Yair,
ReplyDeleteTechnically we already used an HTML-based help system. All our content is written in XML and then transformed into HTML. We utilize Microsoft's CHM format to deliver these HTML files, along w/associated GIF, CSS, and JS files, wrapped in a browseable/searchable package. This system does allow us to hyperlink to content on ni.com, which we do frequently (for example, linking to KnowledgeBase or Developer Zone articles). I haven't researched whether we can include SWF or other video files (AVI, MPG, etc) into CHMs. My guess is that if we can, it's horribly complicated to do so :-)
But I think what you mean is a more 'open' system capable (not dependent on CHMs or by extension Microsoft IE) of connecting to, or integrating, online content easier than we can now? Is that correct? Or am I projecting my own biases onto your comment :-)
I wasn't very specific, but your biases certainly sound reasonable (not that I care about online content really. I prefer to have better content at the expense of online content).
ReplyDeleteSlightly off topic, but I've been interested in creating my own .chm style help files for a LabVIEW project I've been working on. But the Windows HTML Help Workshop looks a little intimidating especially since you have to write all of the HTML by hand.
ReplyDeleteWhat's an engineer to do? Are there tools that you use at NI to make authoring Help easier?
Absolutely. The main tool we use is FAR, which you can get at http://www.helpware.net/FAR/.
ReplyDeleteWe also do write HTML by hand, but that is not a requirement of the CHM format. I'm pretty sure you could use an editor like Dreamweaver or Frontpage and that would work just as well.