sentenz/article-technique

Article Technique

Instructions pour les agents IA sur la création, la révision et la révision d'articles techniques utilisant un langage formel, une structure cohérente, une terminologie précise, des exemples pratiques et des références vérifiables.

• 1. Bénéfices
• 2. Principes
  • 2.1. Langue
  • 2.2. Intégrité du contenu
• 3. Structure
  • 3.1. Fichier et Titre
  • 3.2. Introduction
  • 3.3. Table des Matières
  • 3.4. Sections Numérotées
  • 3.5. Taxonomies et Définitions
  • 3.6. Exemples et Données
  • 3.7. Références
• 4. Flux de Travail
  • 4.1. Créer
  • 4.2. Réviser
  • 4.3. Vérifier
• 5. Guide de Style
  • 5.1. Voix et Ton
  • 5.2. Terminologie
  • 5.3. Phrases et Paragraphes
  • 5.4. Listes et Citations en Bloc
  • 5.5. Liens et Citations
  • 5.6. Code, Tableaux et Admonitions
• 6. Portes de Qualité
• 7. Ressources
• 8. Références

1. Bénéfices

• Cohérence

  Une grammaire stable de l'article rend le contenu technique prévisible d'un sujet à l'autre et permet aux lecteurs de localiser les définitions, les catégories, les principes, les exemples et les références sans réapprendre la structure du document.

• Lisibilité

  Des paragraphes de définition concis, des titres explicites et des listes de termes et définitions réduisent la charge cognitive tout en préservant la précision technique.

• Navigabilité

  Une table des matières hiérarchique maintenue manuellement et des titres numérotés exposent la hiérarchie conceptuelle et fournissent une navigation directe pour les longs articles.

• Réutilisabilité

  Les taxonomies, les listes de terminologie, les exemples pratiques et les références qualifiées rendent chaque article utile à la fois comme introduction et comme référence technique durable.

• Vérifiabilité

  Des règles de formatage et de preuve déterministes permettent aux relecteurs de séparer les défauts structurels, les défauts linguistiques et les inexactitudes techniques.

2. Principes

2.1. Langue

• Formel

  Utiliser un anglais neutre adapté aux ingénieurs logiciels, aux ingénieurs systèmes, aux professionnels de la sécurité et aux décideurs techniques.

• Encyclopédique

  Définir le sujet avant de prescrire des pratiques. Expliquer ce qu'est un concept, comment il est catégorisé et où il est appliqué avant de présenter des recommandations.

• Précis

  Privilégier les noms et verbes spécifiques au domaine plutôt que des termes larges ou promotionnels. Distinguer les normes, spécifications, protocoles, outils, cadres, pratiques, métriques et modèles architecturaux.

• Impersonnel

  Privilégier les constructions impersonnelles ou à la troisième personne. Éviter la narration à la première personne, l'adresse directe à la deuxième personne, les questions rhétoriques et les remplissages conversationnels.

• Déclaratif

  Énoncer directement les définitions, relations, contraintes et résultats. Utiliser les verbes modaux uniquement pour exprimer une exigence, une recommandation, une possibilité ou une incertitude réelle.

2.2. Intégrité du Contenu

• Preuve

  Soutenir les affirmations vérifiables de l'extérieur par des sources faisant autorité. Privilégier les organismes de normalisation, la documentation officielle, la recherche primaire et les dépôts canoniques.

• Actualité

  Vérifier les faits sensibles au temps, les comportements spécifiques à une version, les seuils de performance, les exigences légales et les capacités des produits avant de les inclure.

• Portée

  Centrer chaque article sur un seul sujet technique. Lier aux articles adjacents plutôt que de dupliquer un contenu contextuel important.

• Cohérence Taxonomique

  Grouper les concepts par une seule dimension de classification explicite à la fois. Ne pas mélanger outils, pratiques, résultats et propriétés comme des pairs, à moins que la section n'explique la relation.

• Exemples

  Utiliser des exemples syntaxiquement valides, techniquement plausibles et directement liés à l'explication précédente.

3. Structure

3.1. Fichier et Titre

• Nom du Fichier

  Utiliser un nom de fichier en minuscules avec des traits d'union qui identifie le sujet, par exemple dette-technique.md, interrupteurs-de-fonctionnalités.md, ou systèmes-de-fichiers.md.

• Préambule

  Ne pas ajouter de préambule YAML aux fichiers d'article, sauf si le dépôt cible l'exige explicitement.

• Titre H1

  Commencer par exactement un titre H1 contenant le nom canonique du sujet en casse de titre.

  # Interrupteurs de Fonctionnalités
  

3.2. Introduction

Placer un ou deux paragraphes concis immédiatement après le titre H1.

1. Définition

   Définir le sujet dans la première phrase. Développer un acronyme lors de la première utilisation lorsqu'il n'est pas universellement évident dans le domaine de l'article.

2. Contexte

   Expliquer le but du sujet, son rôle opérationnel ou sa relation avec le génie logiciel. N'introduire aucune taxonomie détaillée avant la table des matières.

Exemple :

# Interrupteurs de Fonctionnalités

Les interrupteurs de fonctionnalités sont des contrôles d'exécution qui activent ou désactivent un comportement d'application sans nécessiter un nouveau déploiement. Ils découplent le déploiement du code de la publication de fonctionnalités et prennent en charge le déploiement contrôlé, l'expérimentation et l'atténuation opérationnelle.

3.3. Table des Matières

Insérer une table des matières Markdown maintenue manuellement après l'introduction et avant la première section H2.

• Hiérarchie

  Refléter chaque titre numéroté H2, H3 et H4 significatif avec une indentation de deux espaces par niveau.

• Étiquettes

  Inclure le préfixe numérique complet et le texte du titre.

• Ancres

  Utiliser des ancres en minuscules compatibles avec GitHub. Supprimer la ponctuation selon les règles de titrage GitHub tout en préservant les traits d'union entre les mots.

• Complétude

  Ajouter, supprimer ou renommer les entrées de la table des matières chaque fois que les titres changent.

Exemple :

- [1. Catégorie](#1-catégorie)
  - [1.1. Stratégies de Déploiement](#11-stratégies-de-déploiement)
    - [1.1.1. Déploiement Bleu-Vert](#111-déploiement-bleu-vert)
    - [1.1.2. Déploiement Progressif](#112-déploiement-progressif)
- [2. Principe](#2-principe)
- [3. Bonne Pratique](#3-bonne-pratique)
- [4. Terminologie](#4-terminologie)
- [5. Références](#5-références)

3.4. Sections Numérotées

Utiliser une numérotation décimale arabe dans chaque titre d'article en dessous de H1.

• H2

  Utiliser ## 1. <Section> pour les sections de premier niveau.

• H3

  Utiliser ### 1.1. <Sous-section> pour les sections de deuxième niveau.

• H4

  Utiliser #### 1.1.1. <Sujet> uniquement lorsqu'une sous-section contient une taxonomie substantielle qui nécessite un autre niveau.

• Profondeur

  Privilégier quatre niveaux de titres maximum, y compris H1. Remplacer une profondeur de titres excessive par des listes de termes et définitions ou des tableaux.

• Sections Canoniques

  Sélectionner uniquement les sections qui contribuent au sujet. Les étiquettes courantes compatibles avec le corpus incluent Bénéfices, Catégorie, Principe, Principes, Bonne Pratique, Terminologie et Références.

• Ordre

  Commencer par les concepts et catégories fondamentaux, continuer avec les principes ou pratiques, puis conclure avec la terminologie et les références.

3.5. Taxonomies et Définitions

Utiliser la prose pour les transitions conceptuelles et les listes de termes et définitions pour le contenu technique pouvant être parcouru.

• Introduction de Section

  Ouvrir une section majeure avec un ou deux paragraphes qui expliquent la dimension de classification ou le but de la section.

• Modèle Terme-Définition

  Présenter une étiquette technique comme une puce et son explication comme une citation en bloc indentée.

  - Atomicité
    > L'atomicité garantit qu'une transaction se termine comme une seule unité ou est annulée sans conserver un résultat partiel.
  

• Modèle Groupé

  Utiliser un élément de liste ordonnée comme titre de groupe local lorsqu'une sous-section contient plusieurs points de vue distincts, comme des conventions, des exemples ou des outils.

• Capitalisation des Étiquettes

  Utiliser la casse de titre pour les étiquettes conceptuelles et la casse de phrase pour les descriptions.

• Qualité de la Description

  Commencer les descriptions par le rôle, le comportement ou la propriété définissante du terme. Éviter les définitions circulaires qui répètent l'étiquette sans ajouter de sens.

3.6. Exemples et Données

• Exemples Autonomes

  Introduire des exemples autonomes au niveau de la prose avec Exemple :. Dans les sous-sections groupées telles que Exemples et Explications, utiliser une étiquette descriptive d'exemple à la place.

• Exemples de Code

  Utiliser un bloc de code délimité avec l'identifiant de langage le plus précis.

• Syntaxe en Ligne

  Utiliser des accents graves pour les commandes, les chemins de fichiers, les clés de configuration, les identifiants, les littéraux et les fragments de syntaxe courts.

• Tableaux

  Utiliser des tableaux Markdown pour les comparaisons compactes, les matrices, les métriques, les commandes ou les données de référence énumérées. Garder le contenu des cellules parallèle et éviter les paragraphes en prose à l'intérieur des cellules.

• Diagrammes

  Utiliser des diagrammes textuels tels que Mermaid lorsque les relations ou les flux ne peuvent pas être expliqués efficacement avec de la prose ou un tableau.

• Admonitions

  Utiliser les admonitions GitHub avec parcimonie pour les contraintes, les mises en garde, les liens croisés ou les informations qui modifient matériellement l'interprétation.

  > [!NOTE]
  > Le seuil de la métrique dépend de la période de rapport citée et doit être vérifié avant la publication.
  

3.7. Références

Terminer chaque article par une section numérotée Références.

• Références Internes

  Utiliser des liens relatifs au dépôt pour les articles Sentenz connexes.

  - Article Sentenz sur le [Versionnement](../articles/versionnement.md).
  

• Références Externes

  Nommer l'organisation ou l'éditeur avant le titre lié et identifier le type de source après le lien.

  - Publication du NIST [Secure Software Development Framework (SSDF) Version 1.1](https://csrc.nist.gov/pubs/sp/800/218/final).
  - Documentation Kubernetes [Documentation](https://kubernetes.io/docs/).
  - Dépôt GitHub [DORA Four Keys](https://github.com/dora-team/fourkeys).
  

• Types de Sources

  Utiliser un qualificatif précis tel que article, documentation, page, publication, dépôt, rapport, spécification ou norme.

• Pertinence

  Inclure uniquement les sources citées ou utilisées matériellement dans l'article. Ne pas créer de liste de lecture générale sans lien avec les affirmations de l'article.

4. Flux de Travail

4.1. Créer

1. Inspecter

   Lire les fichiers voisins dans le répertoire cible de l'article. Enregistrer le vocabulaire de titrage local, le style de lien, les conventions de blocs de code et les articles internes connexes.

2. Portée

   Définir le sujet de l'article, la profondeur prévue et la dimension de classification primaire. Séparer les sujets adjacents en articles liés croisés.

3. Recherche

   Collecter des sources primaires faisant autorité. Vérifier la terminologie, les normes, les métriques, le comportement du produit et les détails sensibles au temps.

4. Plan

   Sélectionner les sections canoniques requises et construire une hiérarchie de titres numérotés avant de rédiger la prose.

5. Charger le Modèle

   Charger assets/technical-article-template.md lors de la création d'un nouvel article. Supprimer les sections qui ne contribuent pas au sujet.

6. Rédiger l'Introduction

   Écrire le titre H1 et un ou deux paragraphes de définition. Établir le sujet et le contexte d'ingénierie sans précharger les détails d'implémentation.

7. Construire la Table des Matières

   Refléter la hiérarchie de titres planifiée et générer des ancres exactes compatibles avec GitHub.

8. Rédiger les Sections

   Ajouter des introductions de section, des listes de termes et définitions, des exemples, des tableaux, des diagrammes et des admonitions uniquement là où ils améliorent la compréhension.

9. Ajouter des Références

   Ajouter des liens internes relatifs et des références externes qualifiées par source. S'assurer que chaque affirmation externe matérielle a une source faisant autorité appropriée.

10. Valider

    Appliquer toutes les Portes de Qualité avant de retourner ou de soumettre l'article.

4.2. Réviser

1. Préserver l'Intention

   Identifier le sujet, la portée et la taxonomie de l'article existant avant de modifier la structure.

2. Charger le Modèle

   Charger assets/technical-article-template.md avant de réviser l'article. L'utiliser comme référence structurelle, supprimer les sections de modèle inapplicables et préserver les sections valides spécifiques à l'article.

3. Diagnostiquer

   Séparer les défauts en précision technique, taxonomie, organisation, langue, formatage, liens, exemples et références.

4. Normaliser

   Aligner le titre, l'introduction, la table des matières, la numérotation, les niveaux de titres, les listes, les citations en bloc, les blocs de code et les références avec cette compétence.

5. Affiner la Langue

   Remplacer les termes vagues, répétitifs, conversationnels ou promotionnels par des définitions techniques directes et des verbes appropriés au domaine.

6. Réconcilier la Navigation

   Mettre à jour les ancres, les liens croisés et les références après chaque changement de titre ou de nom de fichier.

7. Valider

   Réexécuter toutes les portes de qualité et confirmer que la révision ne supprime pas d'informations techniquement pertinentes sans raison explicite.

4.3. Vérifier

1. Charger le Modèle

   Charger assets/technical-article-template.md avant de vérifier un article. L'utiliser comme référence structurelle et ne pas signaler les sections facultatives omises comme des défauts, sauf si leur absence crée un problème d'exhaustivité ou de cohérence.

2. Évaluer

   Vérifier l'article dans l'ordre suivant :

   1. Exactitude Technique
   2. Portée et Cohérence Taxonomique
   3. Conformité Structurelle
   4. Terminologie et Acronymes
   5. Exemples, Tableaux et Diagrammes
   6. Liens et Références
   7. Grammaire, Ponctuation et Lisibilité

3. Signaler les Constatations

   Signaler les constatations avec le titre ou la ligne concerné, le défaut, sa conséquence technique et une correction concrète. Prioriser les erreurs factuelles et les incohérences structurelles par rapport aux préférences stylistiques.

5. Guide de Style

5.1. Voix et Ton

• Présent

  Utiliser le présent pour les définitions, les capacités et les pratiques actuelles.

• Passé

  Utiliser le passé uniquement pour les événements historiques ou les comportements obsolètes.

• Voix Active

  Privilégier la voix active lorsque l'acteur ou le mécanisme est important.

• Voix Passive

  Utiliser la voix passive lorsque le processus ou le résultat est au centre et que l'acteur n'est pas pertinent.

• Perspective Impersonnelle

  Éviter les pronoms de première et deuxième personne.

• Profondeur ...

[Le contenu complet a été tronqué pour la traduction. Les sections restantes suivraient le même schéma de traduction.]

6. Portes de Qualité

Cette section est réservée à la définition de contrôles de qualité spécifiques. Les portes de qualité doivent être complétées par des critères mesurables.

7. Ressources

Cette section est réservée à la liste des ressources associées, telles que les modèles et les outils.

8. Références

Cette section est réservée à la liste des références externes et internes.