Software technical manual

[thoult]

Documentation. We all hate it. But we all need to do it.

Hopefully, we all document our LV code as we progress through it (or at least blitz it when someone pulls us up on it). There are a number of tools for doing this within the LabVIEW environment.

However, what do you outside of LV? If your software is visible to external customers, you probably hopefully have some standards for what you need to produce. The software will be a black box to the customer, so you don't actually have to document the inner workings.

As a process developer working on automated test software, my customers are internal to my company: other LV engineers who may need to maintain code, production engineers and technical managers. The first group should be able to interrogate well documented code, but will need additional information that can't be documented there. The first group can afford to be ignorant of the inner workings of the code, and probably just want to know how to reinstall components and/or hardware when things go wrong, as well as troubleshooting. The last group will, most likely, be unable and unwilling to read through LV code to determine how certain algorithms work, but may want to know how the test coverage is achieved, especially if they need to solve product related issues or design new processes.

The following is a brief summary of the sections I include:

• System architecture: system diagrams showing hardware components and connections; I/O map
• Software architecture: required LV and RIO versions, installer location, additional installers, user account requirements, FPGA code, RT code, communication methods, PC code, any intraprocess API documentation
• Test sequence or process flow
• State code description: outlines, verbosely, what occurs in every state, including the test coverage that is achieved in each and any algorithms and references that need defining. This is a pain, as it's replicating in long form something that a good LV engineer can figure out in little time, but is necessary for 'lay' engineers
• Data storage: local storage methods, network storage methods, SQL storage
• Troubleshooting: typical hardware failures, typical SW failures, typical test failures

Currently, this document is up to some 15,000 words. I don't really want to create additional work for myself by adding much more to it, but are there any other things you'd expect to see in such a document? It'd be nice to get a feel for others and the sorts of things they add. Unit tests, functional tests and others are recorded elsewhere, so I don't see any need to repeat it here.

I'm aware all of our documentation requirements and methods will be different. Some of you will see this as overkill, no doubt, but considering that this process has the potential to require maintaining and updating in some twenty years time still, it's something that needs doing!

[Hooovahh]

Sound pretty complete to me.  But in my world I usually end up making 3 documents, sometimes more sometimes less.  The three I have usually have the same amount of information as yours, but the idea is the intended audience can change for each document.

Software Design Document

• System architecture: system diagrams showing hardware components and connections; I/O map.  This also usually shows high level relationships between Actors/Engines.
• Software architecture: required LV and RIO versions, installer location, additional installers, user account requirements, FPGA code, RT code, communication methods, PC code, any intraprocess API documentation
• Actor/Engine communication methods.  This is mostly optional but can be auto generated so who cares.  It describes each actor, and each method that each actor has, and describes the intended purpose of the methods.  This can all be pulled from the VI descriptions of the actors and methods.
• Test sequence or process flow
• Data storage: local storage methods, network storage methods, SQL storage

User Manual

• How to install the software on a fresh machine, and configure it.
• Screenshots of each interactable UI element with a quick description of what the purpose of each control is.  This usually is a bulleted list for each UI.
• Troubleshooting: typical hardware failures, typical SW failures, typical test failures

Quick Start Guide

• A 4-5 page document that describes the process of starting a test, assuming the software has already been configured, and the options of starting the test and their purpose.  This may have some overlap with the User Manual but this should be minimized so only one document needs to be updated when changes are made to the software.

[thoult]

Excellent, thanks Hooovahh - that's exactly the sort of info I'm looking for from others. I skipped to the bullet points before reading your comment, and thought "wow, he really does the same stuff as I d...oh wait, he's expanded and rearranged my original list"! 🙂

My software ships as part of an electromechanical test platform, so as well as this, there are:

- full CAD models and drawings stored in our CAD system, accessible anywhere in the company

- technical files satisfying regulatory requirements for any custom electronics that isn't CE marked, plus any electromechanical systems. There are three for this jig: one for the overall tooling, one for the main electronics interface and one for a secondary electronics interface

- mechanical build manual, which highlights any considerations that an assembler should need to take when considering the assembly drawings. For my jig, this is a set of Powerpoint slides some 50 pages long. For another jig, it is 250 pages long, because it's that complicated

- system commissioning manual, which explains the mechanical, electrical and software commissioning processes

- software technical manual

- golden unit creation guide, which is a procedure that outlines the steps to create a new daily check unit for the process

- preventative maintenance instructions, which define the routines (some purely mechanical, some software driven but still fully documented) that must be carried out regularly

- work instructions, which is kept with the equipment. This serves as the training guide and record for operators

- critical process intent document, explaining why certain design decisions were made in the software, hardware etc

That's even before you consider all the requirements, test coverage, unit testing, functional testing, update validation, process change documentation etc etc etc. As much of a pain in the neck as these all are, there are products being made by processes here that are over 25 years old.

Many of these are inherently obvious as to what they should contain: the mechanical build manual for instance. Others are well defined in my company, such as work instructions.

The software technical manual, however, is somewhat open to interpretation, hence trying to get an idea from others as to what they include.

[Hooovahh]

Yeah I'm not sure what our fill package even contains but there are other things in there like schematics, drawings, CAD, etc.  That being said the scenario I described was for internal purposes mostly.  The quick start guide was sent out to technicians at testing houses on occasion.  

My point with mentioning that is in those situations we never had a complete package, just some "Hey do we have some documentation for this software", and me saying "Yup go here to find it."  It was more political than a requirement from a customer.  It was a bit strange but it also helped continue the usage of a process to help do things right even if we didn't really have to.  

It also helped when management would go out and try to get quotes for outside software work done, because we could point to a list of features and documentation that we could do in house that the outside guys either wouldn't, or would charge extra for.  Not that I'm against going to outside houses, but their reasoning of it'll be cheaper, done faster, and done better, wasn't going to fly with me.  Wow quite a tangent sorry.

[thoult]

---

@Hooovahh wrote:

My point with mentioning that is in those situations we never had a complete package, just some "Hey do we have some documentation for this software", and me saying "Yup go here to find it."  It was more political than a requirement from a customer.  It was a bit strange but it also helped continue the usage of a process to help do things right even if we didn't really have to.

---

I know exactly what you mean. I'm not entirely sure that my customers actually know what they want or whether it might be necessary, but the whole drive is to bulletproof the process against staff turnover, version and platform migration...plus my project manager is understandably keen that support from me is kept to a minimum.

They're all things that we think would be worth writing down, but as a lot of these things have either never been done or have been done poorly, it's tough to know where to draw the line and/or what to include.

And surely tangents are what this board exists for? 🙂

[Ben]

Notmentioned above .... (???)

A list of custom error codes, waht they are (the number) what the names is for each error, and comments describing what I was looking for and what should be done to fix the error.

Ben

[thoult]

That's a good shout - thanks Ben.