documentation

[Feignedjesse2]

Hello everyone,

I'm currently working as an intern (so yes, i'm a student) at a company that has no knowledge or experience with software and interns. 

In my study, Mechatronics, I learned to work with labview in a basic way. This involved State Machines and basic Master-Slave patterns. 

The program I created now, however, has a completely different layout. The program consists of 7 threads and 50+ SubVI's. 

The program works fine and has a very logical (flow-) layout. Any person with a little knowledge of labview could almost immediatelly see how the program works. 

Because I am an intern, I need to make a report. For previous software projects like State Machines we just used "State Transition Diagram (STD) " to explain the programs to the person reading the report.

Now, however, a STD does not apply here. This is because the program will have no interface, no use cases, no "real" states and is completely automatic: It initializes and then runs something over and over again untill the power will be cut. 

The only documentation i currently have of the software is some flowcharts on how the software operates. This is, however, not enough. 

Does anyone have any experience making these kind of reports, where the readers will be teachers or other students, and must be able to globally understand the program layout/working.

And if so, how did you do this and/or is there a standard for this? 

ps. I found this thing called UML, but I don't know if it actually applies for labview because UML focusses heavily on Classes, which in labview, are not used very often (from what i heard, correct me if i'm wrong).

Kind regards,

Jesse Bax

[Sam_Sharp · Accepted solution]

Essentially you need to create a 'software design document' - this is a document that describes the overall function of the software and details how it is/was implemented.

Typically, a document like this might have the following sections (taking a look at some of my previous documentation - this isn't an exhaustive list):

- Introduction

- System Overview: give an overview of the various hardware/software components and the purpose of the software and how it's designed to be used

- Architecture: give an outline of the overall architecture of the program - what are the main functional modules and how do they interact with each other (e.g. queues/events).

- Design/Implementation: Write a section about each of the modules, showing how they operate - what the states are etc. It's also good to mention any assumptions/goals/problems you had when you were writing the code - this helps another developer to get inside your head and understand the why you did it that way.

It's also a good idea to mention any requirements (e.g. version of LabVIEW, any additional toolkits you used, drivers required etc.) - this helps the next developer work on your software without loading it with loads of missing dependencies etc.

You may also want to create a user manual which tells the end user how to install, configure and use the software - again, lots of screenshots and descriptions of what each button does. For us, this is a separate document but you might want to combine it if it's only a small project.

There should be lots of diagrams (flow charts and state transition diagrams are good for this) and screenshots of the code with explanations. Of course...in reality the software changes over time so this level of documentation can become quite laborious...(but is sometimes necessary!).

Of course, your LabVIEW code should also be well documented - lots of block diagram comments, VI icons and VI descriptions!