How do you develop help files / users manuals...

[Chris Davis]

I wanted to pose a question to the community, to get options for developing help files and users manuals for code that you distribute. I'd like to know, for example, how the VIPM team develops and maintains thier help manual that is delivered with VIPM. Its always been a problem for my group, and I want to know what others are doing.

Software engineering documents/books and experience tells me that the help manual has to be developed and kept in close sync with the code itself. For text based languages there are many tools to accomplish this, doxygen, robodoc, and many others. These tools let you embed the developer documentation inside you code and flag the comments you want pulled out with a special comment marker. You can then automate the creation of the most current help files from the command line in a batch process, allowing you to deliver those manuals with your code. For LabView, the closest thing that exists is the printing functionality that NI provides. This works fine for smaller VI's and small projects, but I'm afraid I've had little success with this form of documentation as my project expands.

To be clear, I'm asking two different questions here. How do members of the LAVA community develop users manuals for thier projects? and How do members of the LAVA community develop documentation for thier code so that other developers can understand that code and add to it?

To be fair, I'll include what I'm doing now to create a users manual for one of our (beta) projects. It is in its infancy, but the pay off is already clear. I use robodoc to convert simple text files into HTML files that are delivered and accessed with my program. The advantages that we are experiencing right now are:

1. Members of the team don't have to know HTML to write documentation for thier code. They can learn a small subset (3 - 4 tags) and create good looking help files, as long as our text files follow the set of robodoc rules, that I've written.

2. Since we are writing simple text files, subversion has an easy time keeping track of any and all changes (subversion diff'ing is great here)

3. We automate the creation of the latest help files in our OpenG Builder prebuild VI. This ensures that we have the most current ** help files avaliable at the time of the build.

4. We also automate the creation of a NSIS build at the end of our OpenG Builder run, ensuring that the "setup.exe" file that is generated also has the most current documentation avaliable to the installer.

**If someone knows how to do a subversion update from the command line on a know directory I would be appricative. I haven't had the time to look it up yet.

I'm really interested in how groups handle developer documentation with LabView. But I would also love to hear from groups who are creating users manuals too.

[crelf]

QUOTE(chrisdavis @ Feb 23 2007, 01:42 PM)

How do members of the LAVA community develop documentation for thier code so that other developers can understand that code and add to it?

I (of course) use the VISTA Help Documentation Generator - it's probably the VISTA tool that I use the most. It creates HTML files and/or Compiled HTML Files (that's those neat chm files that form Windows-style help files) from some user-definable fields including name, icon, VI desctiption, etc. Here's an example of a Compiled HTML File that I just created from The Captain's Tree Control API LAVAcr submission:

Download File:post-181-1172203925.zip

Also, you can get a demo copy of the tool - PM me directly if you're interested in trying it out.

[Jim Kring]

QUOTE(chrisdavis @ Feb 22 2007, 07:42 PM)

I wanted to pose a question to the community, to get options for developing help files and users manuals for code that you distribute. I'd like to know, for example, how the VIPM team develops and maintains thier help manual that is delivered with VIPM. Its always been a problem for my group, and I want to know what others are doing.

Hi Chris,

For VIPM's documentation, JKI uses ComponentOne's Doc-To-Help, which can compile MS Word documents to various forms of help documentation -- we use the HTML output format. This allows us to have cross-platform and web-based help documentation. The documentation process starts by first developing a specification. This is an internal document that describes what the software needs to do, from the perspective of validating the final product's features. Then, once the features are implemented, portions of the spec are used in the final user guide, which is written from the perspective of helping users understand the products features.

Thanks,

[ars_stowers]

I have used Vizacc's (sp?) HelpMaker some in the past. It isn't the best tool in the world, but it is free (not GNU free, just freeware) and works reasonably well.

[Chris Davis]

Chris,

I had heard of the VISTA documentation tools before now, and but I hadn't seen them in action. Thanks for posting an example. I'll have to explore this option to see if it provides me what I'm looking for.

Jim,

Thanks for sharing what JKI uses to document VIPM, I have to admit I was suprised that you use Doc-To-Help. My last experience with the product wasn't good, and I haven't gone back. But because I left them off the list, I didn't know that they would read things besides word documents as source material. I'll also have to take a closer look at it as an option to replace robodoc.

Ars_Stowers

Thanks for your option as well. I'm not against paying for something, especially if it does a good job! I'll have to explore HelpMaker as well, although I do need to be cross platform in some cases, and this product only appears to output windows compiled help files.

[crelf]

QUOTE(chrisdavis @ Feb 24 2007, 02:32 PM)

I had heard of the VISTA documentation tools before now, and but I hadn't seen them in action. Thanks for posting an example. I'll have to explore this option to see if it provides me what I'm looking for.

No problem - the VISTA tools are in a nebulous state right now, but look for a major announcement soon...

[ars_stowers]

QUOTE(chrisdavis @ Feb 23 2007, 10:32 PM)

Ars_Stowers

Thanks for your option as well. I'm not against paying for something, especially if it does a good job! I'll have to explore http://www.vizacc.com/' target="_blank">HelpMaker as well, although I do need to be cross platform in some cases, and this product only appears to output windows compiled help files.

HelpMaker can actually build HTML-Help, Windows help files, Browers Help files, RTFs, OmniHelp files (don't know what these are), JavaHelp files, and can export parts of your project as a PDF.

Don't know if this helps, but I hope so.

[Tomi Maila]

Hi,

I use Adobe Dreamweaver which is a very good HTML editor. I've written Adobe Dreamweaver templates for LabVIEW help pages. I use Microsoft HTML help to generate CHM files from a set of HTML files I create with Dreamweaver. I attach a ZIP of my HDF5 for LabVIEW help file so you can get a feeling on the quality of this method.

http://forums.lavag.org/index.php?act=attach&type=post&id=5033