Co-ordinating several designers on a single project

I've currently writing a best practices/guidelines for a system I'm working on. The system consists of eight Guardlogix processors connected over EtherNet/IP using Stratix 8300 switches. Several of the GuardLogix systems are embedded in other subcontractors' systems. I will be doing the rest; I'm also co-ordinating the project.

So, I want to write a document that outlines how to program and configure the system so that it will be easy to integrate and will have consistency between systems when troubleshooting years down the road.

The project is nearing the end of the conceptual design stage.


Things I have on my list to include are IP address, subnet masks, VLANs. Naming convention for processors, I/O modules, controller-scoped tag names. I'm providing sample code for various functions, emergency stop, end-of-travel limits, etc.

1) What should I include in such a document?
2) What should I not include in such a document?

If you've worked on such a project in the past what pitfalls were there. What did you do right; what did you do wrong?

The two things that seem to get forgotten/put off are how are the individual systems supposed to react relative to each other and what data is required between the sections and how is that data passed. The first item generally defines the second, which is why they are usualy missed as a pair. Unless this is defined early the section designers will most likely miss a response mode that is required by the system, since they don't know it is required. Depending on how modular their programming method is this could result in a big rewrite.

Keith

We do have separate interface documents for each subsystem. Each document has two tables that basically show:
if consume tagA then required subsystem reaction,
if condition then produce tagB.
(the second also includes producing telemetry data on a schedule)

So we've done that. Of course only time will tell if its complete.

You've hit on part of my question, how do you write a guideline for modularization of their programming. I'm thinking of asking for a routine for each line in the table for handling this I/O but worried this might lead to too many routines.

Alot depends on how much you trust the guys writing the code for you. If I were doing this, my specification would end at the section description and the interface requirements. You have already provided them with code examples which should provide a representative example of what you expect the code to look like. At that point I would turn them loose.

If you are concerned about overall structure you should require design reviews at specific points in development. Specific to your last example, tell them not to start detailed coding until they present you with a macro program structure. This could be a document that lists the Task/Program/Routine layout the expect to use or it could be an early copy of the actual code with the structure coded already. Let these guys at least take a cut at practicing their craft before you tie their hands. You may get something good you didn't expect.

Having stated what I just stated, you need to walk a little bit of a fine line between steering them and letting them run relative to reviews of their work. Nothing is more frustrating than, after 3 weeks of work, someone tells you "I don't know what I want but what you just showed me ain't it". I've been on the receiving end of that ne a few times and it just isn't good for morale.

Keith

kamenges said:

Having stated what I just stated, you need to walk a little bit of a fine line between steering them and letting them run relative to reviews of their work. Nothing is more frustrating than, after 3 weeks of work, someone tells you "I don't know what I want but what you just showed me ain't it". I've been on the receiving end of that ne a few times and it just isn't good for morale.

Click to expand...

Thanks for the input. That is exactly what I don't want to do. I take it as a good sign that they want to have a set of written guidelines. I also try to remind them at every chance that this is only a guideline and I've already asked for their input on what they want to see in the way of guidelines.

I don't think I have any special insights into programming the system, I just want it to be unified so that when I'm trying to troubleshot this thing, I don't have try to understand several different versions of the same basic function that were written by different programmers.

Add to this the programmers are across the country and across the Atlantic from me, so its not as easy as walking down the hall to talk to me.

Not knowing your system, I'll share what we do without our Siemens based systems:

- Naming convention. IO's and data. (symbolic and absolute)
- Networking identification. Name, IP, subnets, etc.
- Structure of network comms.
- Block numbering. While the naming convention also includes this, we do demand specific block numbers to be used for specific functions.
Examples: FC 5 and 6 are send/receive blocks. FC 80 - 89 are blocks preserved for processing external communication. FC 30-34 handles the specific stop modes. E-stop, normal stop w/o restart, normal stop with autorestart, etc etc.

This allows better troubleshooting down the line when Bubba doesn't have the original program and needs to upload a copy/do online troubleshooting.

Other then that, do not limit them too much.
I've seen one heck of a speghetti code being the result of trying to achieve something rather simple, but due to the limits imposed, they needed to re-invent the wheel.