Aller au contenu

Documentation soumise à son propre linter

Soumis la documentation à son propre linter — budget de lignes par fichier ne pouvant que diminuer, obligation d'index et contrôle de l'existence des chemins — qui a trouvé six plans sur neuf déclarés terminés avec des cases non cochées et quatorze tâches obligatoires avant commit absentes des documents.

la documentation soumise à son propre linter

Situation. Le dépôt se gouverne par des instructions écrites — vingt‑six documents couvrant la politique qualité, le système de conception, l’accessibilité, l’impression, les métadonnées, la traduction et git. Les instructions ont un mode de dégradation précis : elles s’allongent, divergent du code, se mettent à référencer des fichiers déplacés et, à partir d’une certaine taille, ne sont plus lues. Une règle non lue n’est pas une règle.

Tâche. La documentation avait besoin du même traitement que le code — un linter avec des limites qui provoquent un échec plutôt que de conseiller.

Action. Huit politiques, chacune mécanique. Un plafond strict de longueur de document et un autre plus souple qui avertit. Un budget de lignes par fichier qui ne peut que diminuer, de sorte qu’un document puisse rétrécir sans pouvoir regrossir. Une obligation d’index au‑delà d’un seuil, et d’index de section au‑delà d’un seuil plus bas. Une règle de localisation définissant quel document possède quel sujet. La validité des liens. L’honnêteté des plans — l’état revendiqué par un plan doit correspondre à ses propres cases. Une règle imposant que chaque tâche conditionnant un commit soit nommée dans un document. Et une vérification des chemins réels, pour que chaque chemin qualifié par un répertoire et chaque symbole de code nommé par un document existe réellement. La première exécution a justifié tout l’exercice : six plans marqués terminés avec des cases non cochées, quatorze tâches conditionnant chaque commit et nommées dans aucun document, trois liens cassés, un document orphelin et trois chemins morts dans cinq documents. Le budget a ensuite refusé son propre auteur — ajouter le résumé de ce travail au document de développement dépassait sa limite, ce qui a conduit à créer un document distinct, soit exactement le fonctionnement voulu de la politique.

Résultat. Vingt‑six documents totalisant environ 2 666 lignes effectives, chacun sous un budget qui ne peut pas croître, avec chaque chemin et symbole nommé vérifié contre l’arborescence. Le constat inconfortable mérite d’être répété : quatorze contrôles conditionnaient chaque commit sans figurer dans aucun document ; les règles imposées par la machine et celles lues par les humains avaient donc déjà divergé.

  • Main tenant un stylo au-dessus d’un porte-bloc
    Photo : Mohamed_hassan / Pixabay
  • Dossiers, papiers, documents
    Photo : Tomasz_Mikolajczyk / Pixabay

Mettez cette expérience au service de votre projet

Prenez « Documentation soumise à son propre linter » comme point de départ pour un défi similaire dans votre organisation. Les prestations mobilisées pour cette réalisation sont disponibles pour votre projet. Quelqu'un de votre côté de la table pour apporter un second avis éclairé sur un fournisseur, un budget ou une décision d'architecture.

Découvrir nos prestations Contactez-nous

Examinez ce qui a conduit au résultat

Découvrez la situation, les décisions et le résultat de cet exemple. Nous pouvons discuter des éléments transposables à vos contraintes et de ceux qui nécessitent une autre démarche. Documentation soumise à son propre linter — la documentation soumise à son propre linter

Découvrir nos prestations Contactez-nous

Un élément d'un parcours plus long — entièrement présenté sur ce site.

Chaque entrée suit la même structure : la situation, la tâche, ce que nous avons fait et ce qui a changé.

Voir l'ensemble du parcours

Définissez l'amélioration nécessaire

Présentez la décision, les personnes concernées et les options déjà envisagées. Nous pouvons expliciter les compromis et laisser une recommandation documentée.

Consulter les tarifs Contactez-nous

Votre documentation devient-elle obsolète sans bruit ?

Interrogez-nous sur les décisions qui sous-tendent « Documentation soumise à son propre linter ». Vous parlerez aux personnes capables d'expliquer le travail et d'évaluer votre propre projet.

Découvrir nos prestations
welcome@engineer.company +45 50 10 61 84 Copenhague, Danemark
Code QR pour Soumis la documentation à son propre linter — budget de lignes par fichier ne pouvant que diminuer, obligation d'index et contrôle de l'existence des chemins — qui a trouvé six plans sur neuf déclarés terminés avec des cases non cochées et quatorze tâches obligatoires avant commit absentes des documents.
Emportez cette page avec voushttps://advisory.engineer.company/fr/portfolio/put-the-documentation-under-its-own-linter/