Documenting State Machines

[Mark Yedinak]

That's a good idea.

I had a project a few years back where I had to create tip strips for 1024 indicators. After that I never wanted to see a tip strip again.

I should probably give them another chance.

In addition to using the VI description you could also use the Help Tag using an external help file. There are various tools available for creating, editing and compiling help files. Again, this puts your documentation for all of your VIs into a common place and takes advantage of the context help as well as the help file support.

[crossrulz]

I get the impression that those of us who use LabVIEW for data acquisition and processing operate in very different world than those doing ATE. In ATE, I would imagine that the system requirements are pretty clear from the outset. You know your process, and you know the manner in which you want it automated.

For data processing applications, the development process may be much more iterative, as you may not know what has to happen in step 3 of the processing until you can see the results of step 2. Likewise, the user may not know what his UI requirements are until he sees some initial results. This is especially true when using LabVIEW to develop new processing algorithms.

When the ATE is being developed in parallel with the product, you get the exact same mess as you are talking about. I'm going through that right now. Every other day there is a pin moved, requirement changed, subassembly totally redesigned, protocols changed, etc. Development testing starts and then all of your requirements change again. Needless to say, it is quite frustrating.

[ShaunR]

I just about went off on another rant about my job. Two mornings in a row would be too much.

Reader's Digest version: I do have the luxury, and the pain, of being a "team of one". Everyone else here is working in some variant of C. I interface to a lot of different systems, and those interfaces I insist on documenting. With external documentation. What I was trying to address in my original post is internal documentation for *me* when I have to go back 3 years later and remember what I was doing to reuse code. Unless I get hit by a bus on the way to work someday, the odds of anyone else ever looking at my code are pretty slim, so any code cleanup/documentation of my own software is entirely for my own benefit.

The culture here is to do everything on-the-fly. Mid-range projects ($250k+) and up have SOWs and appropriate top level design docs, but after those pass review, all bets are off. "Design meetings" consist of me and a user sitting down in front of a computer and them telling me something like, "I want a button that will export all this spectra data to Origin." Delivery dates are nebulous as testing is continually ongoing and code can often be delivered at any time. All my customers are internal, and while I can't say money is no object, if someone wants something badly enough someone can generally be found to fund it. The good side of all of this is there is a very strong sense of support for the concept of "do whatever it takes to get it done", but unfortunately it's often accompanied by "just don't bug me about the details until it's done and then I'll let you know if it needs to be changed". That's just the way things work around here.

The good news is that my (relatively new) team leader came to me the other day and suggested we start generating SOWs for even our little 2 week tasks! I got all wide-eyed and he thought I was going to protest, but I happily agreed. It's not detailed design documentation, but you have to start somewhere.

He must have got burned recently...lol. Just think of how cool it would have been to have said "what? like this one?" and plonked a document in his lap

That was how it was at my place. Not any more, he, he. My templates are even on the intranet now. When the nuts are on the block (or whatever the female equivalent is) he/she who has the document wins! Other team members caught on pretty quick that my response to a customers' "that's not what I asked for/want/meant" was a black and white section in the SOW that they had signed. Closely followed by "would you like me to quote you for that feature". Internally I wasn't quite as harsh, but it is extremely good leverage for extending timescales if they don't like what they see because of poor communication. After all, you have proof that you did as asked/described and they signed it!

Ooooh. I sound like a tyrant/quality engineer...lol.

But seriously, My code reflects my documents rather than documents reflecting my code. That was the way I was trained and it has stood me in good stead ever since. I have an answer (in writing) for all the ney sayers and 80% of the documentation before I start coding. And it means I can offload the user manual (another thing I hate doing) to a Technical Writer .

Edited August 11, 2009 by ShaunR

[Cat]

He must have got burned recently...lol. Just think of how cool it would have been to have said "what? like this one?" and plonked a document in his lap

Well, actually it took me all of 5 minutes to put my own notes into a more formal format and plonk it in his lap.

Other team members caught on pretty quick that my response to a customers' "that's not what I asked for/want/meant" was a black and white section in the SOW that they had signed. Closely followed by "would you like me to quote you for that feature". Internally I wasn't quite as harsh, but it is extremely good leverage for extending timescales if they don't like what they see because of poor communication. After all, you have proof that you did as asked/described and they signed it!

I understand what you're saying. However... Throughout this thread, I've been flashing back on a design meeting that we had with one of our user groups about a year into a major project. We had released the beta version of the hardware/software and they had come back to us and told us it was missing a key feature. Something that would take a few months and lots of $$$ to add at that point. This project actually did have several hundred pages of design documents, but nowhere did this feature appear. No, it wasn't our fault it had been overlooked, but it didn't matter. These users couldn't do their job without that feature. So we added it. This sort of thing happens (albeit at a much smaller level) all the time.

Ooooh. I sound like a tyrant/quality engineer...lol.

No, you just sound like an actual engineer. My team leader goes on accasional rants about how despite all our college degrees, none of us operates as a true engineer. I just tell him to put his money where his mouth is. That may have lead to the request for the SOWs.

And it means I can offload the user manual (another thing I hate doing) to a Technical Writer .

Wow, you deliver User Manuals?!? Dang!

We delivered a $2M data acquisition system a couple years ago, and then had to go begging for money to get users trained up on how to install/operate it. We had put together a training manual, but no one wanted to pay our technicians/analysts for a couple days worth of time to take the training. The culture here is for on-the-job training, which was fine for older systems that weren't very complicated. This one had been designed by a committee of several different user groups and was full of all sorts of esoteric functions. The fact that most of the hardware was bleeding edge technology and prone to needing fixing at first (talk about a configuration management nightmare), didn't help, either.

So, here we are two years later, and we're still having to go out with the system when it's deployed. I'm a system developer, not an analyst or a technician. Some of my cow-orkers love the overtime, but as long as my software is working, I personally want to spend as little time as possible on submarines (the usual test platform). We're starting design of the next generation of our system, and I am finally in a postion to influence that. User-level Documentation will be a deliverable. There will be money for training. As we always say before a new project, "This time we're going to do it right!"

[ShaunR]

Well, actually it took me all of 5 minutes to put my own notes into a more formal format and plonk it in his lap.

Steeerike 1! Its rare that engineers have the discipline to keep documentation if the environment doesn't require it. Nice one.

I understand what you're saying. However... Throughout this thread, I've been flashing back on a design meeting that we had with one of our user groups about a year into a major project. We had released the beta version of the hardware/software and they had come back to us and told us it was missing a key feature. Something that would take a few months and lots of $$ to add at that point. This project actually did have several hundred pages of design documents, but nowhere did this feature appear. No, it wasn't our fault it had been overlooked, but it didn't matter. These users couldn't do their job without that feature. So we added it. This sort of thing happens (albeit at a much smaller level) all the time.

Well. That's the other aspect of documentation.....traceability. If the formal project process is followed, the code is traceable right back to the requirements spec (the SOW is usually the response to a requirements spec).

No, you just sound like an actual engineer. My team leader goes on accasional rants about how despite all our college degrees, none of us operates as a true engineer. I just tell him to put his money where his mouth is. That may have lead to the request for the SOWs.

True engineer? Does that mean we all weigh 5 stone, have chronic acne, wear wire framed glasses and have a hunch from sitting at monitors all day? Is that what he means?

Wow, you deliver User Manuals?!? Dang!

Its part of our standard document deliverables, along with drawings and a maintenance manual. 3 paper copies of each (One for the maintenance dept, one by the machine and one for the engineering dept) along with one electronic copy of each on CD.

We delivered a $2M data acquisition system a couple years ago, and then had to go begging for money to get users trained up on how to install/operate it. We had put together a training manual, but no one wanted to pay our technicians/analysts for a couple days worth of time to take the training. The culture here is for on-the-job training, which was fine for older systems that weren't very complicated. This one had been designed by a committee of several different user groups and was full of all sorts of esoteric functions. The fact that most of the hardware was bleeding edge technology and prone to needing fixing at first (talk about a configuration management nightmare), didn't help, either.

Design by committee never works. Too many cooks etc, etc. I'm quite surprised, however that training wasn't part of the deliverables

So, here we are two years later, and we're still having to go out with the system when it's deployed. I'm a system developer, not an analyst or a technician. Some of my cow-orkers love the overtime, but as long as my software is working, I personally want to spend as little time as possible on submarines (the usual test platform). We're starting design of the next generation of our system, and I am finally in a postion to influence that. User-level Documentation will be a deliverable. There will be money for training. As we always say before a new project, "This time we're going to do it right!"

You get overtime?....wow. I've also heard the "This time we're going to do it right!" one before. Next time thay say that ask them what the project risks are and what are the contingency plans to mitigate them. If they stare at you blankly, it going to be the same as the last one. If they bore you silly in the first 2 minutes with schedules and plans, there is hope! You know at least they have thought about it

[Cat]

Its rare that engineers have the discipline to keep documentation if the environment doesn't require it.

True confessions: my first degree was in English, so I don't have the usual aversion to the written word that most engineers have.

True engineer? Does that mean we all weigh 5 stone, have chronic acne, wear wire framed glasses and have a hunch from sitting at monitors all day? Is that what he means?

Of course not! The glasses are generally thick black-framed, with masking tape around the nose bridge.

You get overtime?....wow.

They wouldn't get me on a submarine, otherwise.

We're a bunch of low-paid government engineers here. And until a year or so ago we would "max out", ie work for free, after an increasingly small number of OT hours. One test I was on a sub for 7 days. After day 4, I was working for free. I remember sitting across a table in the crew's mess from two contractors (Electric Boat) who were discussing how they got paid OT 24 hours per day while they were on a sub. I told them they were buying me dinner when we finally got off the boat.

[crossrulz]

Of course not! The glasses are generally thick black-framed, with masking tape around the nose bridge.

A true engineer would use duct tape!!!

Edited August 14, 2009 by crossrulz

[george seifert]

A true engineer would use duct tape!!!

Oh no, no, no. Masking tape is much nerdier.

[ShaunR]

A true engineer would use duct tape!!!

Oh no, no, no. Masking tape is much nerdier.

Tape at all signifies an engineer. Bolt standard geeks use plasters.

True confessions: my first degree was in English, so I don't have the usual aversion to the written word that most engineers have.

First degree? How many have you got?

We're a bunch of low-paid government engineers here. And until a year or so ago we would "max out", ie work for free, after an increasingly small number of OT hours. One test I was on a sub for 7 days. After day 4, I was working for free. I remember sitting across a table in the crew's mess from two contractors (Electric Boat) who were discussing how they got paid OT 24 hours per day while they were on a sub. I told them they were buying me dinner when we finally got off the boat.

Contracting is good money, but it has a lot of downsides and work can be sporaddic. So did they?

[Cat]

First degree? How many have you got?

Just the two. English and Electrical Engineering.

So did they?

Even better, they bought me a whole bunch of margaritas.

[Black Pearl]

A true engineer would use duct tape!!!

No way. If you need to botch (correct english?), at least nobody should see it at first. Spray paint it in RAL 7035 (this is a german standard for colors and 'lichtgrau' is widely used for machines) -> german wikipedia.

Much nerdier even: Get some LEDs that blink from time-to-time like everyone knows from a network hub. Of course only the green LEDs blink, never the red ones.

Felix