Tenir un glossaire de projet comme vocabulaire partagé

Objectif

Un seul endroit où chaque terme utilisé par le projet dans le code, l'interface, la documentation et les échanges a un seul sens, afin que « compte », « client » et « locataire » (tenant) ne puissent pas désigner silencieusement la même chose à trois endroits et des choses différentes à un quatrième.

Prérequis

Un emplacement vers lequel chaque document peut renvoyer (un GLOSSARY.md dans le dépôt ou une seule page de wiki), une personne responsable qui fusionne les modifications, et un accord sur le fait que le terme du glossaire est celui utilisé dans les identifiants et le texte destiné aux utilisateurs. Fowler (cité) décrit la pratique de conception pilotée par le domaine consistant à construire un langage commun et rigoureux entre développeurs et utilisateurs, fondé sur le modèle intégré au logiciel ; le glossaire est ce langage mis par écrit.

Étapes

1. Amorcer la liste à partir des substantifs du modèle de données, des ressources de l'API, et de chaque terme ayant provoqué un malentendu lors d'une relecture ou d'un incident.
2. Utiliser une forme d'entrée unique : le terme ; une définition en une phrase ; ce qu'il n'est pas (quasi-synonymes et différence) ; un exemple ; où il apparaît (table, champ, point de terminaison, écran) ; statut (privilégié, déprécié avec son remplacement, à éviter).
3. Choisir exactement un terme privilégié par concept. Lister les synonymes rejetés comme des entrées qui renvoient vers le terme privilégié, afin qu'une recherche sur le mauvais mot aboutisse quand même à la bonne entrée.
4. Développer les abréviations à leur première occurrence dans chaque document et dans l'entrée elle-même. La RFC 7322 (citée) indique que les abréviations doivent être développées dans les titres de document et lors de leur première occurrence ; le guide de style de Google (cité) demande que le jargon nécessaire soit défini à sa première occurrence ou relié à une définition fiable.
5. Relier la première occurrence d'un terme dans un document à son entrée, plutôt que de le redéfinir en ligne ; les définitions en ligne finissent par diverger.
6. Lorsqu'un concept est renommé, modifier le glossaire dans le même commit que le code et la documentation, marquer l'ancien terme comme déprécié avec la date, et le conserver pendant un cycle de version afin que les anciens journaux et tickets restent lisibles.
7. Revoir le glossaire lorsque le modèle de données change et à chaque version ; supprimer les entrées vers lesquelles personne ne renvoie.

Résultat attendu

Les nouveaux contributeurs et les agents peuvent résoudre n'importe quel terme en une seule étape ; les relecteurs peuvent rejeter un changement qui introduit un second nom pour un concept existant en pointant vers l'entrée correspondante.

Limites et base de vérification

Un glossaire ne tranche pas les désaccords sur le domaine ; il consigne le résultat. Les termes que disent les utilisateurs et les termes qu'utilise le code peuvent légitimement différer, et l'entrée devrait alors indiquer les deux. La procédure est proposée ; aucune mesure de la réduction des malentendus n'est revendiquée.

Portée selon le contexte borné

Un seul sens par terme vaut à l'intérieur d'un contexte borné, pas à l'échelle de toute une organisation. Lorsqu'un projet s'étend sur plusieurs modules ou services de domaine, tenir un glossaire par contexte, chacun avec sa propre personne responsable, et appliquer à l'intérieur la forme d'entrée et la règle du terme unique privilégié. Ajouter une courte table de correspondance entre contextes qui énumère les mots employés avec des sens différents de chaque côté (account en facturation par rapport à l'identité) et la façon dont le concept de chaque côté se transpose vers celui de l'autre ; cette table est la carte de contexte mise en prose. Ne pas renommer un concept dans un contexte pour résoudre une collision avec un autre ; consigner plutôt la collision. Un projet doté d'un modèle unique constitue un seul contexte et n'a besoin que d'un seul glossaire.