Jump to content

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


Recommended Posts

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.

Link to comment

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

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.

Link to comment

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

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,

Link to comment

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.

Link to comment

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...

Link to comment

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.

Link to comment

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

Link to comment

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.

Guest
Unfortunately, your content contains terms that we do not allow. Please edit your content to remove the highlighted words below.
Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

×
×
  • Create New...

Important Information

By using this site, you agree to our Terms of Use.