10. Glosarios, convenciones, acrónimos y terminología del dominio
10.1 Introducción
La documentación técnica necesita un lenguaje común. Si cada persona usa palabras distintas para referirse al mismo concepto, la comunicación se vuelve confusa y el sistema puede terminar reflejando esas inconsistencias. En software, los nombres no son un detalle menor: orientan requisitos, modelos, código, pruebas, mensajes y manuales.
Los glosarios, convenciones, acrónimos y definiciones de terminología ayudan a construir ese lenguaje común. Permiten que usuarios, analistas, desarrolladores, testers, soporte y operación entiendan los conceptos del proyecto de la misma manera.
En este tema estudiaremos cómo definir términos, cuándo crear un glosario, cómo manejar acrónimos, cómo establecer convenciones y cómo mantener consistencia en toda la documentación.
10.2 Por qué importa la terminología
La terminología afecta la comprensión del dominio y la calidad del software. Si un documento habla de "cliente", otro de "usuario" y otro de "paciente" sin distinguirlos, el equipo puede implementar reglas incorrectas o crear datos duplicados. Si una API usa un nombre y el manual otro, soporte y desarrollo pueden interpretar problemas de manera diferente.
Un vocabulario consistente reduce ambigüedad. También facilita búsqueda, trazabilidad y mantenimiento. Cuando los conceptos tienen nombres estables, es más fácil encontrar documentos, clases, tablas, pruebas y reglas relacionadas.
10.3 Lenguaje común del proyecto
La imagen representa un lenguaje común de proyecto construido mediante glosarios, convenciones, acrónimos y terminología del dominio. Alrededor aparecen documentación, requisitos, código, pruebas, soporte y usuarios, todos conectados por el mismo vocabulario.
10.4 Qué es un glosario
Un glosario es una lista organizada de términos importantes con sus definiciones. En documentación de software, puede incluir conceptos del dominio, roles, estados, procesos, siglas, abreviaturas, nombres de módulos y términos técnicos propios del sistema.
El glosario no debe limitarse a copiar definiciones genéricas. Su valor está en explicar qué significa cada término dentro del contexto del proyecto. Por ejemplo, "turno" puede tener significados distintos según el sistema: una cita médica, una franja horaria laboral o una reserva de atención.
Un buen glosario ayuda a que el equipo use el mismo vocabulario en requisitos, pantallas, modelos, código, pruebas y soporte.
10.5 Qué términos incluir
No todos los términos necesitan entrar en un glosario. Conviene incluir aquellos que son importantes, ambiguos, propios del dominio, usados por varias áreas o críticos para reglas de negocio.
También deben incluirse términos que suelen confundirse. Por ejemplo, en un sistema de turnos puede ser necesario distinguir "agenda", "disponibilidad", "turno", "reserva", "cancelación", "ausencia", "profesional" y "especialidad".
Si un término aparece en requisitos, código, base de datos, pantallas y pruebas, probablemente merece una definición clara.
10.6 Cómo escribir una definición
Una definición de glosario debe ser breve, precisa y contextual. Debe explicar qué es el término, cómo se diferencia de otros conceptos cercanos y, si corresponde, incluir ejemplos o reglas asociadas.
No conviene escribir definiciones circulares. Por ejemplo, "una reserva es un turno reservado" no aclara demasiado. Es mejor indicar qué representa, quién la crea, en qué estado puede estar y qué relación tiene con otros conceptos.
Cuando un término tiene restricciones importantes, pueden agregarse notas. Por ejemplo: "Un turno cancelado no puede volver al estado reservado; debe crearse una nueva reserva".
10.7 Ejemplo de glosario
| Término | Definición | Notas |
|---|---|---|
| Paciente | Persona que solicita o recibe atención mediante el sistema de turnos. | Puede reservar, consultar o cancelar turnos según reglas del sistema. |
| Profesional | Persona que brinda atención en una especialidad determinada. | Tiene agenda y disponibilidad asociadas. |
| Turno | Reserva de atención asociada a un paciente, un profesional, una fecha y una hora. | Puede estar disponible, reservado, cancelado o atendido. |
| Disponibilidad | Franja horaria en la que un profesional puede recibir reservas. | No es lo mismo que un turno reservado. |
10.8 Acrónimos y siglas
Los acrónimos y siglas son frecuentes en documentación técnica: API, UI, BD, SLA, JWT, HTTP, JSON, QA, CI/CD. Pueden ahorrar espacio, pero también pueden excluir a lectores que no los conocen.
Una buena práctica es escribir el nombre completo la primera vez que aparece, seguido de la sigla entre paréntesis. Luego puede usarse la sigla. Por ejemplo: "Interfaz de Programación de Aplicaciones (API)".
En documentos extensos o con muchas siglas conviene mantener una sección de acrónimos. Esto es especialmente útil cuando la documentación está dirigida a audiencias mixtas.
10.9 Convenciones de nombres
Las convenciones de nombres definen cómo se nombran elementos del sistema: archivos, módulos, clases, endpoints, ramas, tablas, campos, estados, mensajes, documentos y secciones. Su objetivo es mantener consistencia.
Por ejemplo, una convención puede indicar que los endpoints usen sustantivos en plural, que los estados se escriban con nombres específicos, que los documentos tengan prefijos por tema o que los identificadores de requisitos sigan un patrón.
Las convenciones deben ser simples y aplicables. Una convención demasiado compleja puede ser ignorada. Una convención clara reduce discusiones y mejora búsqueda.
10.10 Convenciones de formato
Además de nombres, pueden definirse convenciones de formato: fechas, monedas, unidades, idiomas, mayúsculas, estilo de comandos, nombres de botones, tablas, ejemplos y bloques de código.
Por ejemplo, un proyecto puede decidir usar fechas con formato día/mes/año en documentación para usuarios, pero formato ISO en APIs. Lo importante es que la convención esté documentada y se aplique de manera consistente.
Las convenciones de formato son especialmente importantes cuando la documentación se comparte entre equipos, países o sistemas externos.
10.11 Terminología del dominio
La terminología del dominio es el vocabulario propio del área de negocio o problema que el software aborda. En salud puede incluir paciente, profesional, turno, cobertura, historia clínica. En educación puede incluir curso, alumno, inscripción, evaluación. En comercio puede incluir pedido, carrito, pago, envío, devolución.
Comprender la terminología del dominio es esencial para documentar correctamente. Si el equipo técnico usa nombres que no coinciden con el lenguaje del negocio, pueden aparecer errores de interpretación y comunicación.
La terminología del dominio debe construirse con participación de personas que conocen el negocio, no solo desde el equipo técnico.
10.12 Relación con modelos y código
Los términos definidos en el glosario deberían relacionarse con modelos, código, base de datos, pruebas y documentación funcional. Si el dominio habla de "turno", pero el código usa "appointment", la base de datos usa "booking" y el manual habla de "cita", el equipo debe decidir si esas diferencias son necesarias o si generan confusión.
No siempre se puede usar exactamente el mismo idioma o término en todas partes, pero las diferencias deben estar justificadas. Lo importante es que exista trazabilidad conceptual: que una persona pueda entender qué elementos representan el mismo concepto.
10.13 Glosario vivo
El glosario no debería ser un documento que se crea al inicio y luego se abandona. Debe evolucionar cuando aparecen nuevos conceptos, cambian reglas, se detectan ambigüedades o se incorporan nuevas áreas del dominio.
Para mantenerlo vivo, conviene asignar responsables, revisarlo junto con cambios funcionales y enlazarlo desde documentos importantes. También puede incorporarse a la revisión de requisitos y modelos.
10.14 Conflictos terminológicos
En algunos proyectos diferentes áreas usan palabras distintas para el mismo concepto, o la misma palabra para conceptos diferentes. Estos conflictos deben resolverse explícitamente. Ignorarlos suele trasladar la confusión al software.
Resolver un conflicto puede requerir elegir un término oficial, aceptar sinónimos controlados o distinguir conceptos que parecían iguales. Lo importante es registrar la decisión y comunicarla.
Por ejemplo, si "reserva" y "turno" se usan como sinónimos, el glosario puede definir cuál será el término principal y en qué contextos se permite el otro.
10.15 Ejemplo de acrónimos
| Acrónimo | Significado | Uso en el proyecto |
|---|---|---|
| API | Interfaz de Programación de Aplicaciones. | Servicios que permiten integrar sistemas externos. |
| BD | Base de datos. | Almacenamiento persistente del sistema. |
| QA | Aseguramiento de calidad. | Actividades de validación y pruebas. |
| SLA | Acuerdo de Nivel de Servicio. | Compromisos de disponibilidad o tiempos de respuesta. |
10.16 Errores frecuentes
Al trabajar con glosarios y terminología suelen aparecer estos errores:
- Crear glosarios con definiciones genéricas que no explican el contexto del proyecto.
- Usar varios términos para el mismo concepto sin aclaración.
- Usar siglas sin definirlas la primera vez.
- No actualizar el glosario cuando cambian reglas o procesos.
- Definir convenciones demasiado complejas para aplicarlas en la práctica.
- No relacionar términos del dominio con modelos, código y pruebas.
- Permitir que cada equipo use vocabulario distinto para conceptos compartidos.
10.17 Qué debes recordar de este tema
- Un lenguaje común reduce ambigüedad en documentación, requisitos, código y pruebas.
- El glosario define términos importantes dentro del contexto del proyecto.
- Las siglas deben explicarse antes de usarse como abreviaturas.
- Las convenciones de nombres y formato mejoran consistencia y búsqueda.
- La terminología del dominio debe construirse con personas que conocen el negocio.
- Los conflictos terminológicos deben resolverse explícitamente.
- El glosario debe mantenerse vivo durante la evolución del sistema.
10.18 Conclusión
Los glosarios, acrónimos, convenciones y términos del dominio ayudan a que la documentación técnica sea coherente y precisa. También fortalecen la comunicación entre áreas y evitan que distintas interpretaciones se transformen en errores de software.
En el próximo tema estudiaremos la documentación de requisitos y la trazabilidad con decisiones posteriores.