PLC programs Documentation - Offtrack question

[passwordg]

This might be a bit off but:

My programming team is told that our ControlLogix programs are hard to follow and we need to make them easier to follow by personnel at other plants.

Part of that process is to write a worded documentation of the programs.
I have not been programming for that long either to know what that even means.
Can anybody help me out on this ? Maybe show me a sample documentation file or something similiar ?

I also need to come up with a specific format and follow that for all subsequent programs. I'm not sure how to begin on that.

 

[James Mcquade]

passwordg,

the word document is simply this, write a word document that describes in detail the sequence of the program. in that description you would document what relays were used, plc output # in relation to the i/o, cad drawing numbers, and so on.

this might take several revesions to get it right.

another suggestion is to use a flowchart or timing diagram.

regards,
james

 

[OkiePC]

Do you create any design documents in advance of writing code?

I would try to come up with a generic document that explains your program design methods, and then add detailed explanations for specific programs.

Typically, I put big overview type of "this is the general approach" stuff in a Word document, and the details right in the rung comments.

 

[tomalbright]

Several things - one, did you receive some sort of "operational document" that allowed you to program the PLC? Basically, what was expected of it. Include that. Also, document what each section of the PLC logic does, and add detail if needed.

Your first statement "our ControlLogix programs are hard to follow" also leads me to believe that you didn't use too many accurate descriptions in your tag names, or even using tag numbers as descriptions. Is this correct? Using someone's "out of the box" program with no cross reference can be tricky. Not impossible, but tricky. You know what they say about what happens when someone "assumes" something.

Be sure and get an example of their existing programs and documentation to use as a model for yours; the old "copy and paste" method is tried and true.

ETA: Okie beat me to it, again, regarding the first section.

 

[passwordg]

Thank you James and OkiePC.

Do you create any design documents in advance of writing code?

No. For the few months I have been working, I keep a mental flowchart in my mind and simply go from there. (As I type this, I realize this is not the right way to proceed.)

I would try to come up with a generic document that explains your program design methods, and then add detailed explanations for specific programs.
Typically, I put big overview type of "this is the general approach" stuff in a Word document, and the details right in the rung comments.

I wish I had a sample document I could see once. I have been looking in Google but have not found anything satisfactory.

 

[passwordg]

Thank you tomalbright.

Your first statement "our ControlLogix programs are hard to follow" also leads me to believe that you didn't use too many accurate descriptions in your tag names, or even using tag numbers as descriptions. Is this correct?

Be sure and get an example of their existing programs and documentation to use as a model for yours; the old "copy and paste" method is tried and true.

No, I have good descriptions and comments. But the other plants worked with PLC 500 till now, not Controllogix 5000 - causing this disparity.
Also, no previous documentation exists right now.

even using tag numbers as descriptions.

Wait. What does this mean ?

 

[tomalbright]

Wait. What does this mean ?

It means, instead of addresses like in the SLC's, you can use a real tag name, like "FT-1001". This would be aliased to your IO, and anyone looking at the program would know immediately what it was.

I am using a program right now where IO is shotgunned throughout, analogs are labelled "Analog[1]", motors are labelled "Motor[1], etc. To find out what it really is, you have to add comments, or backtrack via the HMI to find out where exactly the status is for an item. It's easier now than it was, but to fix this program, and the high school programming style would be a complete rewrite. Try to stay away from that.

If there's a tag scheme used at the plant, that would be very helpful if you were allowed to use that. I think the customer will like Contrologix once they get a nice neat system. It's hard to fathom the difference in addressing - there isn't any set addressing scheme, or tables of addresses. Once they make that hurdle, the world will be right again.

 

[RussB]

This might be a bit off but:
My programming team is told that our ControlLogix programs are hard to follow and we need to make them easier to follow by personnel at other plants.

First thing to do is determine who your audience is. This simple test will tell you volumes about how the documentation needs to be formatted.

Which of these sites is the MOST Humorous:
A: Very Technical
B: Not so Technical

 

[labeledas]

I am writing documentation for a program now, and it is baiscally just describing what the code is doing, in simple english, and whY it was done that way.


Forgive the typos i am using an iPad and have fat fingers

 

[Archie]

This may help show how a document can show how a program works:

http://www.youtube.com/watch?v=rCa_U6YATTA

A well thought out program would start with the document and develop the program based on it.

 

[(8{)} ( .)]

There are several rules that I learned many years ago that have served me well.

1) Document before you write - Basically write dummy rungs (ie. rungs that act as comment anchors) and write comments explaining what you plan to do.

If I had do do just one thing this would be it. The reason that this is so important is that a) if forces you to think through the program before you start coding
b) you automatically end up with documented code!

2) Divide your programs into manageable chunks. Use subroutines even if all you're using them for is to divide your code.

3) Simple and manageable names. Remember that Tag names are names for tags (you heard it here 1st folks) and not descriptions. Use a single standard. For example if you've got 2 pressure transmitters prefix them with the same prefix (ie. PT). Don't call one PT_xxx and the other one Press_yy. I hope that's clear.

Good luck,

(8{)} .)
(Yosi)

 

[passwordg]

Where can I find a sample documentation on a program ?

 

[BobB]

Man - it is good when it just flows! Programmed 3 automated diesel generator power stations that way. Totally out of control.
Never worked in a 'committee' type programming environment - just me - I could not stand it.
However, you have to be organised with respect to your I/O, network addressing etcetera or it will all go wrong.
I do not nor have ever seen a document as you describe. I just get in and do it.