Mantener un glosario del proyecto como vocabulario compartido

Objetivo

Un único lugar donde cada término que el proyecto usa en el código, la interfaz, la documentación y las conversaciones tenga un solo significado, de modo que «account», «customer» y «tenant» no puedan designar en silencio lo mismo en tres sitios y cosas distintas en un cuarto.

Requisitos previos

Una ubicación a la que pueda enlazar cualquier documento (un GLOSSARY.md en el repositorio o una página de wiki), una persona responsable que integre los cambios y el acuerdo de que el término del glosario es el que se usa en los identificadores y en los textos visibles para el usuario. Fowler (citado) describe la práctica del diseño guiado por el dominio (domain-driven design) de construir un lenguaje común y riguroso entre desarrolladores y usuarios, basado en el modelo del software; el glosario es ese lenguaje puesto por escrito.

Pasos

1. Elabora la lista inicial a partir de los sustantivos del modelo de datos, los recursos de la API y todo término que haya provocado un malentendido en una revisión o en un incidente.
2. Usa una única estructura de entrada: término; definición en una frase; qué no es (cuasisinónimos y la diferencia); un ejemplo; dónde aparece (tabla, campo, endpoint, pantalla); estado (preferido, obsoleto con su sustituto, evitar).
3. Elige exactamente un término preferido por concepto. Incluye los sinónimos descartados como entradas que remiten al término preferido, para que la búsqueda de la palabra equivocada también llegue al destino correcto.
4. Expande las abreviaturas en su primer uso en cada documento y en la propia entrada. RFC 7322 (citado) indica que las abreviaturas deben expandirse en los títulos de los documentos y en el primer uso; la guía de estilo de Google (citada) pide que la jerga necesaria se defina en el primer uso o se enlace a una definición fiable.
5. Enlaza la primera aparición de un término en un documento a su entrada en lugar de volver a definirlo en el texto; las definiciones en línea se desvían con el tiempo.
6. Cuando se renombre un concepto, modifica el glosario en el mismo commit que el código y la documentación, marca el término antiguo como obsoleto con la fecha y consérvalo durante un ciclo de versiones para que los registros y tickets antiguos sigan siendo legibles.
7. Revisa el glosario cuando cambie el modelo de datos y en cada versión; elimina las entradas a las que nadie enlaza.

Resultado esperado

Las personas que se incorporan al proyecto y los agentes pueden resolver cualquier término en un solo salto; quienes revisan pueden rechazar un cambio que introduce un segundo nombre para un concepto existente señalando la entrada correspondiente.

Límites y base de verificación

Un glosario no resuelve los desacuerdos sobre el dominio; registra el resultado. Los términos que dicen los usuarios y los que usa el código pueden diferir legítimamente, y entonces la entrada debe indicar ambos. El procedimiento es una propuesta; no se afirma ninguna medición de una reducción de malentendidos.

Alcance por contexto delimitado

Un solo significado por término es válido dentro de un contexto delimitado (bounded context), no en toda una organización. Cuando un proyecto abarca varios módulos de dominio o servicios, mantén un glosario por contexto, cada uno con su propio responsable, y aplica dentro de él la estructura de entrada y la regla del único término preferido. Añade una breve tabla entre contextos que enumere las palabras usadas con significados distintos en cada lado (account en facturación frente a identidad) y cómo se corresponde el concepto de un lado con el del otro; esa tabla es el mapa de contextos expresado en prosa. No renombres un concepto en un contexto para resolver una colisión con otro; registra la colisión. Un proyecto con un único modelo es un solo contexto y necesita un solo glosario.