“Industry standard” documentation

[The15thwiseone]

Hello all,

I recently got a new job working as a controls technician. I have been doing it for 3 months, coming up on 4 now, and the company was adamant about me putting out code rapidly with copy and pasting, and in Allen Bradley using the explort import function.

I have thus far been able to perform my duties well enough that most programs for these simple machines are very easy for me to pick up and wrap my mind around. Started off bumpy but once I got to sequential logic IÂ’ve been zooming through these things. The issue is , I guess; my documentation. I am eagerly looking forward to learning new things and moving from SLC 500 series and omoron plcs to studio 5000 and beyond (adding them to my belt of knowledge).

I wrote a keycard reading program for a SLC 500 and that was what my company was trying to make for the customer for a while…., do you document even development/test code outside of “for test , do not ship with device”? Not meaning to “flout” myself but the last guy apparently failed stupendously at the task.

Outside of naming clearly bits what they are doing, ie “drill forward input” and structuring the rungs in such a way that they make sense to all programmers, and labeling/commenting rungs is there anything that is “universal” standard?

Basically to dummy proof the logic so that programmers of every level can look at it and know what it is doing? That was their primary criticism they had of me.

Thank you for your advice!

 

[James Mcquade]

Welcome to the forum.

everyone has their own style of documentation.
this is what i do and it has served me well.

write down what happens in a step by step order.
for example.
power to slc 500 is applied.
allow time for the systems to initialize - typically ??? seconds
after this time, the program ???? to initialize the scanner
g
h
i.......z
while you are documenting this, give plc program example.
i usually include the timer numbers and preset values.
i also include the I/O terminal to help maintenance understand what they read in the documentation and see in the plc program.
in the plc program, i also document the page and line number of the cad drawing. px2312 is a prox switch on page 23 line 12 of the cad drawing.
when you go to that page, you will also see the brand name and model number of the prox.

Yes, it takes longer to document in this fashion, but maintenance will love you for it and do their best to solve the issue. many of my customers when they saw this documentation started making this a company when they talked to maintenance and discovered that downtime was reduced by 50% because they had the part numbers on the prints and in the plc program.
regards,
james

 

[Saffa]

Code comments and data table / tag descriptions are very valuable yes.

But, even more valuable is a well written Functional Specification provided in both PDF and hard copy. These sorts of things tend to live longer than .RSS files. No one but programmers know the value of these, so they get lost on a floppy disk / CD / DVD / USB somewhere along the line.

I'm always happy to find a paper copy of an FS when I open a cabinet.

Describe what it does, how it works. State machines, IO, etc.

Easier to justify the time and effort to write a good one when you're producing multiple copies of the same machine.