Documenting LabVIEW Code in Word

[Crispy1170]

Hello everyone!

I've been working on a big project in Labview, in short, it's about reading sensor data and controlling a pump + control valve and I have no idea how to document it properly in Word, can anyone give me some tips or does anyone have examples? That would be awesome because I'm really clueless 

[ThomasHenkel]

The first question would be: what do you want to document for whom?
• the code for future changes for colleagues or potential successors?
• or the usability of your software for users?

[Crispy1170]

It's meant for my professor so basically for future successors when other students take over the project and continue on

[ThomasHenkel]

• Short introduction
What should your program do? How should it do it. What is the goal - Why does someone need your program?

• Requirements
List of required hardware and software, e.g., which LabVIEW version, 32-bit or 64-bit?

• Structure
Rough sketch of your setup in the form of a technology diagram. This should show which hardware is installed, where sensors are connected, which sensors are used, etc.

Explanation of how the hardware should work

• Basic structure of your software
Which components communicate with each other and how? Do you have a Main.vi with a main loop or event structure that calls other subVIs? Are any components running in parallel? Are you using a well-known software pattern? Are you using any framework?

• Hardware communication
If you have hardware with more complex communication (e.g., Modbus or SCPI), this should be described.

• Usage
How can someone start your program, what do they need to enter where, and how do they see the results.

Desription of configuration and result files. Desription of used paramters.

This is just a rough suggestion. As you write the individual chapters, you'll surely come up with more ideas about what people should know about your project.
Use UML diagrams where appropriate for processes and temporal dependencies; they usually make it easier to describe things than words.

[Yamaeda]

I'd probably go with some JSP diagram of program flow and leave the implementation to LV (but comment it much and well in the .vi's)

[Bob_Schor]

Before you document your program in Word (or some other program meant for producing human-readable documents, such as LaTeX, which I'm currently using), you should make sure you are thoroughly documenting it in LabVIEW.

Start by organizing the LabVIEW Project (and the structure on disk of the components) into Folders, such as "Main" (Top-level VIs), "Sub-VIs", "TypeDefs", "Documentation" (which would include the Word file you are developing -- a copy should logically "live" with the LabVIEW code), etc.

Every VI, every TypeDef, every other LabVIEW component (such as Libraries) should have its "Documentation" property telling what it does and (at a minimum) enumerating the Inputs and Outputs.

It should go without saying that the LabVIEW Project should be "managed" by some form of Version Control, such as Subversion (which I use) or Git (which is probably the most widely used currently by LabVIEW developers).  Commits to your VCS should also be reasonably descriptive -- don't let a week (or a month!) go by without a Commit!

So now I'm going to revise my first sentence, above.  The "ideal principle" for Software Development is "Write the Documentation First".  The advice you've been given earlier by Thomas Henkel still applies -- you need to understand the Broad Outline of what you want to accomplish, the Inputs and the Outputs, and some notion of "How" to accomplish the tasks your software needs to perform (which I call the "What" it needs to do).  As you start developing "documented" LabVIEW code (and testing it, as you can, as you go), you might find that the "How" changes.  Keep updating the Documentation, both the "Text" (or Word) version, the VCS "Commit" messages, and the individual VI Documentation as you go, so things stay "in synch".

Bob Schor

[crossrulz]

Is there an actual requirement for it to be in Word? If not, you might want to have a look at AsciiDoc, which is based a fairly simple text format that is open and can be rendered into many formats. For an example, the CTI documentation page is written in AsciiDoc. There is even a plugin to create the documentation for you: AsciiDoc for LabVIEW.