Documentation API : ce qu'elle doit contenir et ce qui compte à la remise

1.Pourquoi la documentation API manque presque toujours

Rares sont les projets d'automatisation qui échouent faute de documentation. Ils échouent plus tard – à la première extension, au premier défaut hors des heures ouvrées, au premier changement de programmeur.

La cause est rarement la négligence. Elle est structurelle : la documentation se produit en fin de projet, et c'est en fin de projet que la pression sur les délais est maximale. L'installation tourne, la réception approche, et la question « la documentation est-elle prête ? » entre en concurrence avec « la ligne tourne-t-elle ? ». La réponse est prévisible.

Le résultat, je le retrouve sur presque chaque retrofit : un projet TIA Portal sans commentaires, une table de symboles remplie de Merker_47, un schéma électrique de 2009 et un manuel décrivant une installation qui n'existe plus depuis trois transformations.

2.Les trois niveaux de la documentation API

Une documentation utilisable comporte trois niveaux qui répondent à des questions différentes. N'en livrer qu'un seul, ce n'est pas documenter – c'est remettre du matériel.

2.1.Niveau 1 : dans le code – pourquoi c'est ainsi

Ce niveau répond à la question qu'aucun schéma électrique ne traite : pourquoi est-ce là ?

Le code montre déjà ce qui se passe. Un commentaire qui le répète ne vaut rien :

// ❌ N'apporte rien que le code ne dise déjà
bMotorRun := TRUE;  // démarrer le moteur

Un commentaire prend de la valeur lorsqu'il consigne la raison – surtout pour tout ce qui paraît arbitraire :

// ✅ Consigne pourquoi ce chiffre est ce chiffre
// Temporisation 2 s : la pression hydraulique doit être établie avant
// le démarrage, sinon le retour d'information échoue (exigence
// REQ-HYD-012, procès-verbal de mise en service 2026-03-14)
tDelayStart(IN := bStartRequest, PT := T#2S);
qxMotorStart := tDelayStart.Q;

La règle : toute constante non explicite a besoin d'une source. D'où viennent ces 2 secondes ? Qui a fixé le seuil à 78,5 °C ? Sans cette indication, personne n'osera modifier la valeur dans cinq ans – et l'installation restera figée sur un paramètre que plus personne ne comprend.

Chaque bloc fonctionnel mérite un en-tête avec objet, version et historique :

(*
  Nom :          FB_MotorControl
  Version :      1.2.0
  Auteur :       David Prybisch
  Dern. modif. : 2026-03-14

  Objet :
    Commande moteur standardisée avec temporisation de démarrage,
    surveillance du retour d'information et mémorisation des défauts.

  Interface :
    IN  : bStartRequest, bFeedbackRunning, tTimeoutFeedback
    OUT : qxMotorStart, qxFault, wStatusNamur

  Non couvert :
    Pas de régulation de vitesse – utiliser FB_DriveControl.

  Historique :
    v1.2.0  2026-03-14  Surveillance de timeout ajoutée
    v1.1.0  2025-10-15  Intégration alarmes NAMUR NE 107
    v1.0.0  2025-09-01  Version initiale
*)

La rubrique « Non couvert » est presque toujours omise et compte parmi les plus utiles. Elle évite qu'un bloc soit employé pour un usage auquel il n'a jamais été destiné.

2.2.Niveau 2 : dans le projet – comment l'ensemble s'articule

Ce niveau répond à : comment les éléments s'imbriquent-ils ?

• Vue d'ensemble des blocs, une phrase par bloc. Pas de roman – une phrase indiquant sa responsabilité. TIA Portal permet d'exporter la structure ; la phrase s'ajoute à la main.
• Table des symboles et variables, entièrement commentée. C'est la partie dont l'absence coûte le plus cher : un chargement en ligne sans symbolique est pratiquement illisible.
• Concept de modes de marche : manuel, automatique, réglage, défaut – et les transitions autorisées. De préférence sous forme de diagramme d'états, pas de texte suivi.
• Description des interfaces : quelles données vont vers la supervision, vers le système superviseur, vers l'unité voisine ? Pour OPC UA, joindre la structure de l'espace de noms.
• Liste d'alarmes avec numéro, texte, cause et – plus important que tout le reste – consigne de remise en état. Une alarme « Défaut entraînement 3 » sans consigne n'est qu'une demi-alarme.

2.3.Niveau 3 : le dossier d'installation – ce qui concerne l'exploitant

Ce niveau répond à : que doit savoir l'exploitation sans ouvrir TIA Portal ?

• Configuration matérielle : type de CPU, version de firmware, modules avec références, affectation des adresses, topologie réseau avec adresses IP et noms d'appareils PROFINET.
• Documentation de sécurité : pour les programmes failsafe, la justification selon EN ISO 13849 ou CEI 62061 – fonctions de sécurité, niveau de performance atteint, paramètres F, procès-verbaux d'essai. Ce n'est pas optionnel : cela fait partie de la conformité CE.
• États de sauvegarde : projet archivé avec date, état de l'installation et responsable. Une sauvegarde sans date est un déchet de données.
• Description du redémarrage : que faire après une coupure d'alimentation ? Cette page unique est lue plus souvent que tout le reste réuni.

3.Checklist de remise

Lors de la remise d'une installation, cette liste détermine si l'exploitant pourra travailler seul dès le lendemain. Je la déroule à chaque mise en service :

4.Maintenir la documentation à jour

Une documentation exacte uniquement à la réception est un instantané. Deux choses la font évoluer avec l'installation – et toutes deux sont organisationnelles, pas techniques.

Premièrement : la gestion de versions. Chaque modification du projet reçoit un état et un motif. Avec TIA Openness, les projets s'exportent dans un format texte et se versionnent réellement dans Git – l'historique cesse alors d'être un bloc de commentaires entretenu à la main et découle des commits.

Deuxièmement : documenter tant qu'on se souvient du pourquoi. La modification d'équipe de nuit faite « vite fait » est le début classique d'une dérive documentaire. Deux lignes datées dans l'en-tête du bloc coûtent deux minutes et sauvent le collègue suivant.

Une étape intermédiaire utile : la comparaison en ligne / hors ligne dans TIA Portal indique si l'installation correspond encore à l'état documenté. L'exécuter avant chaque intervention d'ampleur révèle les modifications non documentées avant qu'elles ne deviennent un problème.

5.Quand il ne reste qu'un chargement en ligne

Le cas le plus fréquent en pratique – et la raison pour laquelle les projets de retrofit dépassent leur budget : le projet d'origine a disparu. Il ne reste qu'un chargement depuis la CPU en service, sans symbolique, sans commentaires, en adressage absolu.

Ce n'est pas désespéré, mais c'est laborieux. La démarche qui a fait ses preuves chez moi :

1. Sécuriser le chargement avant toute autre action. Une seconde sauvegarde sur support distinct. L'état que vous trouvez est peut-être la seule source restante.
2. La périphérie d'abord. Les entrées et sorties se raccordent au schéma électrique, au plan de bornes et à l'installation elle-même. Fastidieux mais sans ambiguïté – et c'est l'ancrage de tout le reste.
3. Remonter depuis les actionneurs. Prenez une sortie, suivez par les références croisées les conditions qui la positionnent. Bloc après bloc, une image de la logique se dessine.
4. Nommer dès que compris. Chaque variable identifiée reçoit immédiatement un nom parlant et un commentaire avec la preuve. Reporter, c'est faire le travail deux fois.
5. Vérifier sur l'installation. Ce que vous croyez comprendre doit se confirmer en exploitation. Les tables de visualisation montrent si l'hypothèse tient.

Le résultat d'une telle reconstitution dépasse le simple projet lisible : c'est ce qui rend la prochaine extension de nouveau calculable.

6.Conclusion

La documentation API n'est pas une corvée de fin de projet, mais la condition pour qu'une installation reste maintenable sur tout son cycle de vie. Trois éléments portent l'essentiel du bénéfice :

• Des commentaires qui consignent le pourquoi – surtout pour les valeurs qui paraissent arbitraires.
• Une symbolique complète et commentée – la différence entre un projet lisible et un projet mort.
• Une liste d'alarmes avec consignes – le document réellement lu en cas de défaut.

Traiter ces trois points avec constance apporte davantage qu'un manuel de 200 pages que personne n'ouvre.

7.Pour aller plus loin

• Programmation API : 8 bonnes pratiques pour un code propre – les fondations sur lesquelles repose toute documentation
• Dépannage des programmes API : cerner méthodiquement – là où une bonne documentation paie en cas de défaut
• Les 5 langages de programmation API selon la CEI 61131-3 – quel langage engendre quelle charge documentaire