Como documentar um idioma ubíquo?

Nossa empresa está convertendo muitos processos manuais de negócios (e o conhecimento institucional associado) em novos softwares corporativos. O projeto está indo muito bem, mas, à medida que prosseguimos, fica claro que há muita confusão com relação a termos e definições, tanto no lado comercial quanto no de desenvolvimento.

Conheço os argumentos de Evan para formar uma linguagem onipresente há algum tempo, mas é a primeira vez que preciso documentá-los formalmente. Enquanto olho em volta e tento pensar sobre onde / como documentar nossos termos da UL, estou meio que perdida.

Como outras empresas documentam linguagem onipresente? Este é apenas um dicionário no estilo wiki? Existe alguma ferramenta destinada a esse fim?

Você pode tratar a "documentação de linguagem onipresente" como um projeto de personalização de software: você precisa de um software para gerenciamento de documentação e adaptá-lo às suas necessidades específicas. Nos projetos de software, você normalmente começa com a coleta das necessidades do usuário, constrói a arquitetura da informação e a solução de design e prossegue para a implementação. Abaixo está o exemplo deste processo.

Quais são as necessidades do usuário para isso? Em algumas organizações, pessoas com funções diferentes de domínios diferentes desejam usar o dialeto de idioma comum para descrever seus problemas e soluções. Este dialeto será definido apenas pelo seu vocabulário (palavras e figuras de linguagem), uma vez que a pronúncia provavelmente não é importante aqui e a gramática será baseada na forma de literatura da língua. Para documentar o dialeto, é necessário projetar uma estrutura de documentação que seja mais adequada para gerenciar um vocabulário (glossário de termos).

As pessoas podem querer usar esta documentação para aprender o significado da palavra ou sigla, para encontrar a palavra correta por seu sinônimo ou definição ou para aprender todas as palavras que compõem o domínio.

Para essas necessidades do usuário, o wiki é realmente uma boa escolha. Como isso se encaixa? Em um bom sistema wiki, como o Confluence ou o MediaWiki, é possível:

• Crie um artigo para cada termo.
• Defina a estrutura comum dos artigos em algum modelo, para que eles contenham algumas seções comuns, que podem ser usadas para agregação.
• Adicione facilmente links para definições de termos em outros artigos da wiki.
• Crie tabelas agregadas com definições de termos e incorpore-as em outra documentação.

Atualmente, estou usando o Confluence para documentar a arquitetura da informação e definições de linguagem onipresentes fazem parte dela. O nível mais alto desta documentação são artigos de domínio. Em toda aplicação, existem vários domínios, por exemplo, segurança, pagamentos etc. Esses domínios são definidos por várias interações do usuário com o sistema, que podem ser descritas por meio de linguagem onipresente, por isso, coloco definições dessas interações em subpáginas e definições separadas. de termos introduzidos por essas interações nas subpáginas das páginas de interação. Coloco tabelas agregadas nas páginas pai, para que seja possível ver, por exemplo, quais cenários consistem no domínio e quais termos são definidos nele.

Quando essa estrutura de documentação é concluída e eu vou a especificações mais detalhadas do sistema, posso simplesmente me referir às definições de IA e UL dos cenários, por exemplo, "o componente A implementa a integração com o sistema B para suportar a interação C (link do cenário da IA) passando informações sobre Z (link UL) ".