¿Cómo documentar un idioma ubicuo?

Nuestra compañía está en proceso de convertir muchos procesos comerciales manuales (y el conocimiento institucional asociado) en un nuevo software empresarial. El proyecto está yendo realmente bien, pero a medida que avanzamos, está claro que existe mucha confusión con respecto a los términos y definiciones tanto en el lado comercial como en el desarrollo.

He estado al tanto de los argumentos de Evan para formar un lenguaje ubicuo por un tiempo, pero esta es la primera vez que necesito documentarlos formalmente. Cuando miro alrededor y trato de pensar dónde / cómo documentar nuestros términos UL, estoy un poco perdido.

¿Cómo documentan otras empresas un lenguaje ubicuo? ¿Es esto solo un diccionario de estilo wiki? ¿Hay alguna herramienta destinada a este propósito?

Puede tratar la "documentación de lenguaje ubicua" como un proyecto de personalización de software: debe tomar algún software para la gestión de la documentación y adaptarlo a su necesidad específica. En los proyectos de software, normalmente comienza con la recopilación de las necesidades del usuario, luego construye una arquitectura de información y una solución de diseño y luego procede a la implementación. A continuación se muestra el ejemplo de este proceso.

¿Qué necesita el usuario para ello? En algunas organizaciones, las personas con diferentes funciones de diferentes dominios quieren usar un dialecto de lenguaje común para describir sus problemas y soluciones. Este dialecto se definirá únicamente por su vocabulario (palabras y figuras retóricas), ya que la pronunciación probablemente no sea importante aquí y la gramática se basará en la forma literaria del idioma. Para documentar el dialecto, debe diseñar una estructura de documentación que sea más adecuada para administrar un vocabulario (glosario de términos).

Es posible que las personas quieran usar esta documentación para aprender el significado de la palabra o acrónimo, para encontrar la palabra correcta por su sinónimo o definición o para aprender todas las palabras que componen el dominio.

Para estas necesidades de los usuarios, wiki es una buena opción. ¿Cómo encaja? En un buen sistema wiki como Confluence o MediaWiki es posible:

• Crea un artículo para cada término.
• Definir la estructura común de los artículos en alguna plantilla, para que contengan algunas secciones comunes, que se pueden usar para la agregación.
• Agregue fácilmente enlaces a definiciones de términos en otros artículos wiki.
• Cree tablas agregadas con definiciones de términos e incrústelas en otra documentación.

Actualmente estoy usando Confluence para documentar la arquitectura de la información y las definiciones de lenguaje omnipresentes son parte de ella. El nivel más alto de esta documentación son artículos de dominio. En cada aplicación hay múltiples dominios, por ejemplo, seguridad, pagos, etc. Estos dominios se definen por una serie de interacciones del usuario con el sistema, que se pueden describir a través de un lenguaje ubicuo, por lo que pongo las definiciones de estas interacciones en subpáginas separadas y definiciones. de términos introducidos por estas interacciones en las subpáginas de las páginas de interacción. Pongo tablas agregadas en las páginas principales para que sea posible ver, por ejemplo, en qué escenarios se compone el dominio y qué términos se definen en él.

Cuando termine esta estructura de documentación y vaya a especificaciones más detalladas del sistema, simplemente puedo referirme a las definiciones IA y UL de los escenarios, por ejemplo, "el componente A implementa la integración con el sistema B para soportar la interacción C (enlace de escenario IA) pasando información sobre Z (enlace UL) ".