Documenting Graphical Languages

[Ryykker]

Anybody familier with acceptable methods of customer documentation for applications written using LabView? Also, What should a customer reasonably expect from a consultant that is providing a set of custom vi's in terms of documentation provided to the customer (eg. Interface Control Document?, or requirement complience matrix document?) If anyone has experience in not only writing the LabView application, but also providing good documentation, I would like to hear your ideas. Thanks.

[Wiebe@CARYA]

Hi,

For my own prjects, I extract the VI export string, front panel picture,
diagram picture, hierachy picture and control and indicator coordinates. I
convert the export strings to valid XML and I use a style sheet to convert
this to HTML. This HTML file also has links to calling VI's and VI's called.
I also put XML formatted comment in state machines states, and use this
information to add links from one state to calling states.

I use the file/directory structure to generate a TOC file, and a list of all
the VI's to create an index.

I use HTML Workshop command line to create a chm file of it. The result is a
very compact (4.5MB for 600 VI project), including pictures, links, VI
documentatio, control and indicator information, and state machine
documentati
on. All by running one VI...

The code has fixed paths to source and destination directories, so it is not
very flexible. I intend to fix this in the future, and probably make it
public.

Hope I gave you some inspiration..

Wiebe.



"Ryykker" wrote in message
news:50650000000800000048E00000-1079395200000@exchange.ni.com...
> Anybody familier with acceptable methods of customer documentation for
> applications written using LabView? Also, What should a customer
> reasonably expect from a consultant that is providing a set of custom
> vi's in terms of documentation provided to the customer (eg. Interface
> Control Document?, or requirement complience matrix document?) If
> anyone has experience in not only writing the LabView application, but
> also providing good documentation, I would like to hear your ideas.
> Thanks.

[Methis Elddir]

Hi Wiebe,

That sounds like a very clever utility. Looks multi-platform too. Any
chance you'll setup a project page on OpenG?

[Wiebe@CARYA]

The thought has crossed my mind... Thing is, we are a commercial business.
I've seen some licenses where you can download and use the software for
free, and only have to pay for commercial usage. To me, that seems fair. I
do like to hear your thoughts about the subject...

As for multi platform, I don't know if nux's support .chm files (with the
little expeciance I have with Linux, I suspect it is supported). I did my
best to keep the uncompressed documentation pure HTML, so that part is
multi-platform.

Regards,

Wiebe.



"Methis Elddir" wrote in message
news:40e5cef6@newsgroups....
> Hi Wiebe,
>
> That sounds like a very clever utility. Looks multi-platform too. Any
> chance you'll setup a project page on
OpenG?

[djs_at_eaton]

Our aerospace business is developing some fairly strict revision control requirements. For documentation, I use the standard LabVIEW tools and send the information to a *.rtf file. I edit that as required in WORD format.

I provide at least a front panel and instructions for the operator. If you enter control descriptions (right click the control, Description and Tip), you can either activate the automatic help or have the documentation tools print it. That gives a headstart for operator instructions.

If I need a software design document, I can add block diagrams with explanations.

I've developed LabVIEW utilities to extract hierarchy information exportable to word processor or spreadsheet format.

I set the VIs to prompt for a comment
at each revision level. I have other utilities to extract comments after any date. Makes it easy to track revisions.

Import front panels, block diagrams, or hierarchies directly into WORD using Print Screen to copy them to the clipboard. V pastes them into WORD. WORD's edit functions allow you to annotate them.

[Methis Elddir]

On Mon, 05 Jul 2004 09:18:25 +0200, Wiebe@CARYA wrote:

> The thought has crossed my mind... Thing is, we are a commercial business.
> I've seen some licenses where you can download and use the software for
> free, and only have to pay for commercial usage. To me, that seems fair. I
> do like to hear your thoughts about the subject...

Honestly, I'm way too biased to give a straight answer (looking at my
"Free as in Freedom" book on my shelf). I can only justify purchasing SW
like LV because it adds so much value to my business, i.e. my clients use
it so I use it.

Sometimes a business provides free SW as an alternative way of circulating
the business name. Whether to go with free or fee really depends on how
you need to do busines
s. For now, what you could do is simply password
protect all the VIs until you make a decision. That way you can get
feedback from users.

> As for multi platform, I don't know if nux's support .chm files (with the
> little expeciance I have with Linux, I suspect it is supported). I did my
> best to keep the uncompressed documentation pure HTML, so that part is
> multi-platform.

I've never heard of these compiled html help files. I'd probably just use
pure html. For linux support I found these sites:

HTML Help Maker (hhm) and soon chm.
http://bonedaddy.net/pabs3/hhm/index.html

CHM lib0.35 for translating the chm files.
http://66.93.236.84/~jedwin/projects/chmlib/

[Wiebe@CARYA]

"Methis Elddir" wrote in message
news:40ecb122@newsgroups....
> On Mon, 05 Jul 2004 09:18:25 +0200, Wiebe@CARYA wrote:
>
> > The thought has crossed my mind... Thing is, we are a commercial
business.
> > I've seen some licenses where you can download and use the software for
> > free, and only have to pay for commercial usage. To me, that seems fair.
I
> > do like to hear your thoughts about the subject...
>
> Honestly, I'm way too biased to give a straight answer (looking at my
> "Free as in Freedom" book on my shelf). I can only justify purchasing SW
> like LV because it adds so much value to my business, i.e. my clients use
> it so I use it.
>
> Sometimes a business provides free SW as an alternative way of circulating
> the business name. Whether to go with free or fee really depends on how
> you need to do business. For now, what you could do is simply password
> protect all the VIs until you make a decision. That way you can get
> feedback from users.

For me, the most important thing is I want my software to be used. I prefer
1000 happy users over 1 paying customer (although this obviously depends on
the amount he pays). However it will take me weeks to finish, and that is
without handling feedback. When it is released, who knows how much time it
will take to maintain...

Perhaps I'll give 'free' a change. Just to see what happens... Perhaps not
for this project though. I have several projects running that qualify...

> > As for multi platform, I don't know if nux's support .chm files (with
the
> > little expeciance I have with Linux, I suspect it is supported). I did
my
> > best to keep the uncompressed documentation pure HTML, so that part is
> > multi-platform.
>
> I've never heard of these compiled html help files. I'd probably just use
> pure html. For linux support I found these sites:

Well, the nice thing about the chm files is they are compact. My project
documentation in HTML has:

764 html files, total 1221 kB
1515 png files, total 161 MB (Size on disk 172 MB)

Compiled, one chm file, size 4.1 MB!! So it has to be compressed in some
way.

Also, I get an index, table of content and search option almost free.

> HTML Help Maker (hhm) and soon chm.
> http://bonedaddy.net/pabs3/hhm/index.html
>
> CHM lib0.35 for translating the chm files.
> http://66.93.236.84/~jedwin/projects/chmlib/

I'll check them out when I find time to spend more time on my Linux machine.

Regards,

Wiebe.