Ein Projektglossar als gemeinsames Vokabular pflegen

Ziel

Ein Ort, an dem jeder Begriff, den das Projekt in Code, Oberfläche, Dokumentation und Gespräch verwendet, eine Bedeutung hat, sodass „account", „customer" und „tenant" nicht stillschweigend an drei Stellen dasselbe und an einer vierten etwas anderes bezeichnen können.

Voraussetzungen

Ein Ort, auf den jedes Dokument verlinken kann (eine GLOSSARY.md im Repository oder eine Wiki-Seite), eine verantwortliche Person, die Änderungen mergt, und Einigkeit darüber, dass der Glossarbegriff der in Bezeichnern und nutzerseitigem Text verwendete Begriff ist. Fowler (zitiert) beschreibt die Domain-Driven-Design-Praxis, eine gemeinsame, präzise Sprache zwischen Entwickelnden und Nutzenden aufzubauen, gestützt auf das Modell in der Software; das Glossar ist diese Sprache niedergeschrieben.

Schritte

1. Die Liste mit den Substantiven aus dem Datenmodell, den Ressourcen der API und jedem Begriff befüllen, der in einem Review oder einem Vorfall zu einem Missverständnis geführt hat.
2. Eine einheitliche Eintragsform verwenden: Begriff; Ein-Satz-Definition; was er nicht ist (Beinahe-Synonyme und der Unterschied); ein Beispiel; wo er vorkommt (Tabelle, Feld, Endpunkt, Bildschirm); Status (bevorzugt, veraltet mit Ersatz, vermeiden).
3. Pro Konzept genau einen bevorzugten Begriff wählen. Die verworfenen Synonyme als Einträge aufführen, die auf den bevorzugten Begriff verweisen, damit eine Suche nach dem falschen Wort trotzdem ankommt.
4. Abkürzungen bei der ersten Verwendung in jedem Dokument und im Eintrag selbst ausschreiben. RFC 7322 (zitiert) besagt, dass Abkürzungen in Dokumenttiteln und bei der ersten Verwendung ausgeschrieben werden sollten; Googles Styleguide (zitiert) verlangt, dass notwendiger Fachjargon bei der ersten Verwendung definiert oder mit einer verlässlichen Definition verlinkt wird.
5. Das erste Vorkommen eines Begriffs in einem Dokument mit seinem Eintrag verlinken, statt ihn inline erneut zu definieren; Inline-Definitionen driften auseinander.
6. Wird ein Konzept umbenannt, das Glossar im selben Commit wie Code und Dokumentation ändern, den alten Begriff mit Datum als veraltet markieren und ihn für einen Release-Zyklus behalten, damit alte Logs und Tickets lesbar bleiben.
7. Das Glossar überprüfen, wenn sich das Datenmodell ändert und bei jedem Release; Einträge löschen, auf die niemand verlinkt.

Erwartetes Ergebnis

Neue Mitwirkende und Agenten können jeden Begriff in einem Schritt auflösen; Reviewer können eine Änderung, die einen zweiten Namen für ein bestehendes Konzept einführt, unter Verweis auf den Eintrag ablehnen.

Grenzen und Prüfbasis

Ein Glossar klärt keine Meinungsverschiedenheiten über den Fachbereich; es hält das Ergebnis fest. Begriffe, die Nutzende verwenden, und Begriffe, die der Code verwendet, dürfen sich legitim unterscheiden, und der Eintrag sollte dann beide angeben. Das Vorgehen ist ein Vorschlag; es wird keine Messung verringerter Missverständnisse behauptet.

Geltungsbereich nach Bounded Context

Eine Bedeutung pro Begriff gilt innerhalb eines Bounded Context, nicht über eine ganze Organisation hinweg. Erstreckt sich ein Projekt über mehrere Fachmodule oder Dienste, ein Glossar pro Kontext führen, jedes mit eigener verantwortlicher Person, und die Eintragsform sowie die Regel des einen bevorzugten Begriffs darin anwenden. Eine kurze kontextübergreifende Tabelle hinzufügen, die Wörter auflistet, die auf jeder Seite mit unterschiedlicher Bedeutung verwendet werden (account im Billing gegenüber Identity) und wie das Konzept der einen Seite auf das der anderen abbildet; diese Tabelle ist die Context Map in Prosa. Ein Konzept in einem Kontext nicht umbenennen, um eine Kollision mit einem anderen zu lösen; die Kollision stattdessen festhalten. Ein Projekt mit einem einzigen Modell ist ein einziger Kontext und braucht ein Glossar.