Creating "help" systems for users (not other LV programmers) - where to start?

[cebailey]

How should one approach giving users a built-in "Help" system?  Users, that is, of a distributed application written in LabVIEW.
 
These users ideally would have no way of knowing the application was written in LabVIEW.  To them, this application is just another program.  The way the LabVIEW Help system works would be fine, but all the content would be inappropriate.
 
From the docs I see we can write "Descriptions" that show up in context-sensitive help when the user puts the mouse over a control, and a "Tip" that shows up when the context-sensitive help isn't even enabled.  Are these typically the only help features built into a distributed application?
 
In the LabVIEW Help there is an article called "Development Process Tips" discussing creating web pages that document the VIs that you create, and another article called "Linking VIs to HTML Files or Compiled Help Files.  Another discusses Creating Compiled Help Files, but refers to third-party software for doing this.  Is this a typical approach for doing a nice job of providing help?
 
Or is there some other way to create a Help system that works like the existing LabVIEW help but has content we create?

[JLS]

Hello,
 
Let me take your questions in order:
 
Q. How should one approach giving users a built-in "Help" system?
A. Here's one approach I have used: 
a). Give all front panel controls and indicators a description so that the context help will show information for those front panel objects, and also for relevant front panel objects a tip - this will pop-up when the user hovers over the object, and can be annoying if it's used excessively, but nice if used where appropriate.
b). Create html files, one for each "Page" of your user interface, and place a Help button on your user interface which will launch the corresponding document for that "Page."  I'm not sure what your UI is like, but basically if there are multiple front panels the user will see, a page describing each object on that panel, and the panel's purpose is nice.  If you're using a tab control in any of those panels, then a page for each tab is nice as well.
 
A variation of b). is to use a so-called compiled help file - a .chm file.  These are only relevant for Windows machines, so if you plan to deploy across multiple OSs, then this is out.  The reason documentation suggests you need a third party tool is because those .chm files basically collect a set of html files together into a nice document, with the usual search, index, browse etc. capabilites and we don't have a product which does this.  The LabVIEW Help on Windows is a nice example of a .chm file.  You can do something SIMILAR with just HTML and javascript, creating at least a contents page which has organized links to the rest of the pages (which themselves can contain links back to the contents page), and even include the ability to search keywords etc.  You'll find various free examples of such html and javascript on the web.
 
Once you have your html or compile help file, you can use the LabVIEW Help VIs to launch them.  For chm files you can open the file and direct to a particular page of the chm file, and for html files all you really need to do is launch the relevant html file in the browser of your choice.
 
 
Q. In reference to descriptions and tips for controls/indicators: "Are these typically the only help features built into a distributed application?"
A. No, the html or chm idea is a nice touch, and can add a professional feel to the application.
 
 
Q. In reference to html or chm files: "Is this a typical approach for doing a nice job of providing help?"
A. Yes, it is used internally as a standard - chm for windows and html for linux and MAC.
 
 
Q. "Or is there some other way to create a Help system that works like the existing LabVIEW help but has content we create?"
A. One ideas is that you could implement your help entirely in LabVIEW if you'd like.  Basically you would be launching your own VI or VIs which would show whatever documentation you wanted/created.  You could use a tree structure or something to provide some convenient navigation by topic, and even a search - you would be coding this, and although I haven't done it, it seems like it would be pretty easy to do.
 
 
I hope this helps, and happy LabVIEW programming!
 
Best Regards,
 
JLSMessage Edited by JLS on 08-30-2006 01:57 PM

[DonRoth]

I want to convert a manual I have created into an on-line, searchable help file that the user can search thru.&nbsp; I have seen this done using the following product in a java-based program:http://www.doctohelp.com/SuperProducts/DocToHelp/It is pretty impressive and would add significant value to my software executable that I am distributing.So the question is, is a searchable help file created with the method you show the link to (<a href="http://zone.ni.com/reference/en-XX/help/371361A-01/lvhowto/creating_help_files/" target="_blank">create a chm file to use with LabVIEW</a>. )?Thanks,Don

[jpaul]

Don,
Yes, the Microsoft HTML Help Workshop that is referenced in the NI document that you linked to in your post will compile your HTML files into a *.chm file which is searchable in the same format as any standard Windows help interface.
Cheers,
JonahApplications EngineerNational Instruments

[DonRoth]

Hi Jonah -OK - I saved my manual to .htm format.&nbsp; I then downoaded the MS HTML
Help Workshop Tool and followed the directions at the following link
create a help file (.chm file):

http://www.beansoftware.com/ASP.NET-Tutorials/HTML-Help-Workshop.aspx
I then made the necessary modifications to the project (HTML Help Workshop Tool Project) in order to display a search tab.
I created a simple test.vi that shows that the .chm file will open with the search tab.&nbsp; <img src="Loading Image..."> What I cannot figure out right now is why my images from the .htm file will not display in the .chm file.&nbsp;&nbsp; I searched the MS HTML Help Workshop Tool help but so far have not come up with what the issue might be.&nbsp; Any thoughts on this?Sincerely,DonMessage Edited by DonRoth on 08-04-2008 07:35 PM


help.png:
http://forums.ni.com/attachments/ni/170/346512/1/help.png

[jpaul]

Hi Don,
I was able to successfully create a searchable help file using the tutorial that you provided as well as the LabVIEW VI to call it (see attached screenshot). One difference is that I used a possibly newer version of the MS HTML Help Workshop Tool found at this <a href="http://www.softpedia.com/progDownload/HTML-Help-Workshop-Download-68169.html" target="_blank">location</a>. Please try downloading it and reproducing the issue with it. Thanks!
Cheers,
JonahApplications EngineerNational Instruments


help_doc.JPG:
Loading Image...

[DonRoth]

I'm at NIweek - will try tonite but can you try something real quick? Can you cut and paste a screen capture into your htm document, recreate the chm file, and see if the screen capture image shows up in the help window?

[jpaul]

Hi Don,
&nbsp;
I also tried to compile my help chm with an image linked inside the htm file. It also worked successfully (see screenshot); however, I did initially run into a snag that may be why your image is not displaying. Is your htm, image and chm file all on the same drive (i.e. C drive)? Because by default Microsoft was saving my chm file to a network drive which was unable to then link back to my htm and image file and gave me an error.
&nbsp;
I hope you are enjoying NIWeek!
&nbsp;
Cheer,
&nbsp;
JonahApplications Engineer
National Instruments


help_doc2.JPG:
Loading Image...

[waldemar.hersacher]

Microsofts security rules will not allow you to open a chm-file over a network unless you make changes to the registry. A tool for doing that is <a href="http://www.ec-software.com/products_hhreg.html" target="_blank">here</a>.
&nbsp;
To get a really working version of the MS HTML Help workshop use the first link from this <a href="http://www.ec-software.com/downloads_mscomp.html" target="_blank">page</a>.
&nbsp;
If you really plan to make a professional user help system use a professional tool like <a href="http://www.ec-software.com/products_hm_overview.html" target="_blank">H&amp;M</a>.
To get an impression how profesional user help is structured, divided into working procedures and reference part, how dialogs are designed containing basic information about what to do here take a look into to the <a href="http://www.helpandmanual.com/help/" target="_blank">online manual</a>.
&nbsp;
Sorry it's a lot of advertising for just one product but I use it regularly and I'm as most a fan of it as of LV.

[DonRoth]

Internet at the hotel has been spotty so am using the lobby terminal.&nbsp; My images are direct&nbsp;cut and pastes into the document using a screen/region capture utillity.&nbsp; So if I have to say where they are resident, well, they were resident at one time on the clipboard, and then directly pasted into the MS Word .doc.&nbsp; I then resave the Word .doc to a .htm file.&nbsp; I suspect then that the&nbsp;inserted images&nbsp;are all being saved to a subfolder (don't have this in front of me) which may be why they are not being found.&nbsp; When I started searching the help utility on images and similar terms, I did not find what I was looking for regarding this issue.
&nbsp;
I am going to download the MS tool and the professional tool refered to in the last message because I know how important the documentation issue can be.
&nbsp;
Will report my results.
&nbsp;
Thanks,
&nbsp;
Don
&nbsp;
ps. NIWeek was fun and educational as usual.&nbsp; I gave a presentation this year also which I think was received fairly well, and partially mentioned (5 minutes worth) the software product I am working on...Message Edited by DonRoth on 08-07-2008 03:34 PM