Manter um glossário do projeto como vocabulário compartilhado

Objetivo

Um único lugar em que cada termo usado pelo projeto no código, na interface, na documentação e nas conversas tenha um só significado, de modo que "account", "customer" e "tenant" não passem a designar, sem ninguém perceber, a mesma coisa em três lugares e coisas diferentes num quarto.

Pré-requisitos

Um local para o qual todos os documentos possam apontar (um GLOSSARY.md no repositório ou uma página de wiki), um responsável que faça o merge das alterações e o acordo de que o termo do glossário é o termo usado nos identificadores e nos textos voltados ao usuário. Fowler (citado) descreve a prática do domain-driven design de construir uma linguagem comum e rigorosa entre desenvolvedores e usuários, baseada no modelo presente no software; o glossário é essa linguagem posta por escrito.

Passos

1. Monte a lista inicial a partir dos substantivos do modelo de dados, dos recursos da API e de todo termo que já tenha causado um mal-entendido numa revisão ou num incidente.
2. Use um único formato de verbete: termo; definição em uma frase; o que ele não é (quase-sinônimos e a diferença); um exemplo; onde aparece (tabela, campo, endpoint, tela); status (preferido, obsoleto com indicação do substituto, evitar).
3. Escolha exatamente um termo preferido por conceito. Registre os sinônimos rejeitados como verbetes que remetem ao termo preferido, para que a busca pela palavra errada ainda leve ao lugar certo.
4. Expanda as siglas no primeiro uso em cada documento e no próprio verbete. A RFC 7322 (citada) diz que as abreviações devem ser expandidas nos títulos dos documentos e no primeiro uso; o guia de estilo do Google (citado) pede que o jargão necessário seja definido no primeiro uso ou ligado a uma definição confiável.
5. Faça a primeira ocorrência de um termo em um documento apontar para o verbete, em vez de redefini-lo no meio do texto; definições embutidas acabam divergindo.
6. Ao renomear um conceito, altere o glossário no mesmo commit do código e da documentação, marque o termo antigo como obsoleto com a data e mantenha-o por um ciclo de release, para que logs e tickets antigos continuem legíveis.
7. Revise o glossário quando o modelo de dados mudar e a cada release; exclua os verbetes para os quais ninguém aponta.

Resultado esperado

Novos colaboradores e agentes conseguem resolver qualquer termo em um único passo; revisores podem rejeitar uma alteração que introduza um segundo nome para um conceito já existente, bastando apontar para o verbete.

Limites e base de verificação

Um glossário não resolve divergências sobre o domínio; ele registra o resultado. Os termos que os usuários dizem e os termos que o código usa podem legitimamente diferir, e nesse caso o verbete deve indicar ambos. O procedimento é uma proposta; não se afirma que haja medição de redução de mal-entendidos.

Escopo por contexto delimitado

Um significado por termo vale dentro de um contexto delimitado (bounded context), não em toda a organização. Quando um projeto abrange vários módulos de domínio ou serviços, mantenha um glossário por contexto, cada um com seu próprio responsável, e aplique dentro dele o formato de verbete e a regra do termo preferido único. Acrescente uma tabela curta entre contextos que liste as palavras usadas com significados diferentes de cada lado (account em cobrança versus identidade) e a correspondência entre o conceito de um lado e o do outro; essa tabela é o mapa de contextos em forma de texto. Não renomeie um conceito em um contexto para resolver uma colisão com outro; registre a colisão. Um projeto com um único modelo é um único contexto e precisa de apenas um glossário.