Documentation et qualité
Une extension partenaire doit pouvoir être comprise sans lire son code. La documentation explique le contrat public et ses garanties ; elle ne doit ni inventer des capacités ni recopier des détails internes d’implémentation.
Sources de vérité
Appliquez la règle suivante : absence d’information fiable > précision inventée.
- les paramètres et outputs Ormuz-owned sont documentés à partir de leur contrat réel ;
- les objets et champs provider viennent de la documentation ou du schéma officiel du fournisseur ;
- une normalisation Ormuz peut documenter une sémantique supplémentaire uniquement lorsqu’elle est explicitement définie par le contrat ;
- lorsqu’un champ reste ambigu, laissez son aide incomplète plutôt que de synthétiser une définition trompeuse.
Décrire champs et outputs
Une bonne description répond à ce que représente la valeur, quand elle est disponible, quelles unités ou cardinalités s’appliquent et quelle garantie le consommateur peut en tirer.
Évitez les tautologies comme « status: the status » ou « amount: the amount ». Pour un output de provider, distinguez clairement soumission, traitement intermédiaire et résultat final lorsque le fournisseur les sépare.
Un exemple ne doit pas devenir une règle normative. Les limites, enums et invariants exécutables appartiennent au contrat structurel et devraient être générés ou validés depuis leur source canonique.
Erreurs et warnings
- documentez les erreurs qu’un utilisateur ou un Agent peut réellement traiter ;
- n’exposez pas le message brut d’un fournisseur comme contrat stable sans validation de sécurité ;
- gardez les warnings dans le canal d’observabilité partagé, pas dans les outputs métier ;
- si un résultat est incomplet et que le consommateur doit le savoir, encodez cette incomplétude dans le contrat du résultat plutôt que dans un warning opérateur uniquement.
Localisation
Les identifiants techniques restent stables ; les labels, descriptions, exemples et messages destinés aux utilisateurs sont localisables. Ne placez pas de texte éditorial dans une structure qui doit rester sérialisable et indépendante de la locale.
Les traductions doivent préserver la même garantie métier. Une traduction plus vague ou plus forte que la source crée un drift de contrat.
Choisir le bon rendu documentaire
Choisissez un format adapté à l’information : un schéma pour expliquer un flux, un exemple de code pour illustrer une intégration ou un tableau pour comparer des options.
| Nature du contenu | Rendu attendu |
|---|---|
| Flux, architecture, relation ou séquence conceptuelle | Schéma compact et lisible sans zoom. |
| Commande CLI ou extrait de code | Extrait de code avec indication du langage. |
| JSON strict | Exemple JSON valide et lisible. |
| Appel HTTP avec payload JSON | Méthode et URL, suivies du corps JSON de la requête. |
| Contrat exhaustif, matrice ou comparaison | Table. |
| Choix parallèles | Cartes comparatives. |
| Parcours ordonné | Liste d’étapes. |
| Invariant, garantie ou avertissement important | Encadré clairement identifié. |
Checklist de review
- Le use case et le moment où utiliser la contribution sont-ils explicites ?
- Les paramètres, sorties, cardinalités et limites correspondent-ils au comportement de l’extension ?
- Les effets externes et résultats intermédiaires sont-ils distingués ?
- Autorité, permissions, classification et risk level ne sont-ils pas confondus ?
- Les erreurs et comportements de retry sont-ils sûrs et actionnables ?
- Les sources provider sont-elles officielles ou explicitement établies par Ormuz ?
- La documentation explique-t-elle le comportement observable sans demander au lecteur de connaître le code de l’extension ?