What are the best practices for documenting and maintaining your automation projects?

El lema debe ser: "Cambio hecho, cambio documentado" Cuando menor sea el tiempo entre la realización del cambio y la modificación de la documentación, menos información se va a perder en el proceso. Cuando más tiempo pase más detalles de todo tipo se pierden. Los cambios que no se documentan automáticamente se pierden y luego hay que hacer un proceso de ingenieria inversa para 'redescubrir' la modificación original. Esto aplica al hardware y cableado además de la parte de software que nunca está lo suficientemente documentada. Más de una vez hemos tenido que sacar el funcionamiento de algunos bloques usando la simulación del programa para deducir su comportamiento ante la variación de las entradas.

One most important thing that you can’t forget: Backup plans - Plan in advance for backup plan of each stage so that you are ready if anything goes wrong Not always will go as planned in industrial automation, it is dependent industry and it relies on supply of various materials, manpower and extra money if needed. Industrial automation brings together many skilled trades and it is always a challenge to hire different varieties and include them in the project development stages. Their opinions are often ignored and managers treat them as hourly employees who are just supposed to do their job. I believe that they can help you defining the most realistic timeline of execution stage.

En mi opinión lo óptimo sería documentar el cambio en revisión "para ejecución" o similar, luego realizarlo, y solo después de supervisar y probar el cambio, archivar la documentación con revisión "as-built".

Yo creo que en eso coincidimos todos, de que así debe ser, pero también seguro que coincidimos en muchas veces por desgracia no es así, y toca hacer de detective.

Es imprescindible tener una metodología en la que se debería identificar: áreas implicadas, dominios de cambio, tipos de cambios (para dedicar más o menos recursos y procesos de aprobación), exigencias de verificación y validación, así como de gestión documental. Las áreas implicadas son cada vez más, desde la parte de control, a la de instrumentación, eléctrica, comunicaciones o ciberseguridad. Dentro de los dominios de cambio indicar Instrumentación y actuadores, lógica programada, laminas de control en HMI local y/o SCADA, cableado de se?ales, redes de comunicación y control, aplicación de parches, control de versión de firmware, de sistema operativo o de aplicaciones, y ahora también de APIs

Another possibility is to create systems for code generation. In combination with databases or Excel tables in which the conventions are stored, a Visual Basic script in combination with an AI can generate a lot of code automatically. Of course, you can also use more established systems here, but simple access and start is also very important.

Consistency and meaningful naming conventions are vital in documentation for variables, functions, files, folders, and other elements of your automation project. This practice minimizes confusion, errors, and duplication while enhancing code readability, understanding, and maintenance. Adhere to recommended naming conventions of your programming language, platform, or framework. Alternatively, establish your convention based on principles like descriptive names, avoidance of abbreviations, and using camel case or underscores to separate words.

Comments are one of the most important topics for documentation. However, there are a few things to consider when using them: 1. Comments should not duplicating the code. Instead they should focus on explaining technical details which don't come clear from the code itself. 2. Have network comments and separate larger function blocks (i.e. SIEMENS TIA Portal) into multiple logical groups. 3. Get sure your language is clear and specific. In particular, don't use slang or jokes. 4. Ensure consistency when commenting. For example, a standardised function block should be written with a predefined module header in place that explains basic data such as the version, date and author.

Comments and annotations are invaluable tools for documenting your automation project. They enable you to add explanatory notes, instructions, references, or warnings to your code, diagrams, or documents without altering functionality or appearance. Comments clarify logic, document assumptions, highlight changes, or flag issues. Use comments liberally but judiciously, adhering to best practices such as using a standard format, updating them regularly, and avoiding redundancy or irrelevance.

Los comentarios en el código sirven para que otro programador o tu yo del futuro sepa interpretar qué has hecho y porqué lo has hecho así.

Version control is crucial in robotics, and GitHub excels by facilitating efficient collaboration. It allows teams to centralize code, track changes, and ensure every modification is documented—vital for systems where changes have broad impacts. GitHub's branching lets teams work on different project aspects without interference, enhancing productivity. Pull Requests ensure code meets quality standards before integration, crucial for maintaining robotics system integrity. GitHub's CI/CD tool integrations automate testing and deployment, ensuring updates perform well and integrate seamlessly into complex systems, accelerating improvements and reducing malfunctions.

Most projects I walk into are brownfields. This means code is not versioned, not backed up and sometimes not documented. I find Software Defined Automation to be key asset in firstly understanding the code using their AI PLC auto description feature but then doing versioning and securing to make sure the current configuration has a point in time and historical reference.

Pues allí va un par de consejos: - Hacer un respaldo del proyecto con cada cambio realizado. - Declarar variables del PLC (primeramente pues muchos ni eso hacen) con coherencia (nada de "tag_1" por ejemplo). - Mantener actualizada la lista de se?ales (físicas como las que van por bus). - Comentar las secciones más importantes del código, comentar cada línea satura y estorba. - De ser posible juntar varios proyectos de los PLC en un multiproyecto, ya que tener regados los proyectos individuales es poco práctico. - Dividir el código en rutinas y/o bloquea funcionales.

3D/XR tools in particular facilitate communication as they make information easily accessible regardless of language and level of education (a picture is worth a thousand words). Therefore, visual communication and AR in the real environment can speed up communication and avoid costly errors. One of the most expensive mistakes in automation projects is still when someone forgets a column in a hall and therefore the automation solution cannot be set up.

Best practices for documenting and maintaining automation projects include thorough documentation of code, outlining the project's purpose, architecture, and dependencies. Utilizing version control systems like Git ensures tracking changes and collaboration. Incorporating clear comments within the code aids understanding and troubleshooting. Regularly updating documentation to reflect changes maintains accuracy. Additionally, establishing testing protocols guarantees functionality across updates. Consistent monitoring and logging facilitate identifying and resolving issues promptly. Lastly, fostering a culture of knowledge sharing within the team ensures project continuity and scalability.