Jak udokumentować język wszechobecny?

Nasza firma jest w trakcie przekształcania wielu ręcznych procesów biznesowych (i powiązanej wiedzy instytucjonalnej) w nowe oprogramowanie dla przedsiębiorstw. Projekt idzie naprawdę dobrze, ale w miarę postępów staje się jasne, że istnieje wiele nieporozumień dotyczących terminów i definicji zarówno po stronie biznesowej, jak i programistycznej.

Od jakiegoś czasu zdaję sobie sprawę z argumentów Evana, by stworzyć wszechobecny język, ale po raz pierwszy potrzebowałem ich formalnie udokumentować. Kiedy się rozglądam i próbuję zastanowić się, gdzie / jak udokumentować nasze warunki UL, jestem trochę zagubiony.

Jak inne firmy dokumentują wszechobecny język? Czy to tylko słownik typu wiki? Czy jest jakieś narzędzie przeznaczone do tego celu?

Możesz traktować „wszechobecną dokumentację językową” jako projekt dostosowywania oprogramowania: musisz wziąć oprogramowanie do zarządzania dokumentacją i dostosować je do swoich potrzeb. W projektach oprogramowania zwykle zaczynasz od zebrania potrzeb użytkowników, następnie budujesz architekturę informacji i rozwiązanie projektowe, a następnie przystępujesz do wdrożenia. Poniżej znajduje się przykład tego procesu.

Czego potrzebuje użytkownik? W niektórych organizacjach osoby o różnych funkcjach z różnych domen chcą używać dialektu w języku wspólnym do opisywania swoich problemów i rozwiązań. Ten dialekt będzie definiowany wyłącznie przez jego słownictwo (słowa i cyfry mowy), ponieważ wymowa prawdopodobnie nie jest tutaj ważna, a gramatyka będzie oparta na formie literackiej języka. Aby udokumentować dialekt, musisz zaprojektować strukturę dokumentacji, która będzie najbardziej odpowiednia do zarządzania słownictwem (glosariusz terminów).

Ludzie mogą chcieć użyć tej dokumentacji do poznania znaczenia słowa lub akronimu, znalezienia poprawnego słowa według jego synonimu lub definicji lub do nauki wszystkich słów, które składają się na domenę.

Dla tych potrzeb użytkowników wiki jest rzeczywiście dobrym wyborem. Jak to leży? W dobrym systemie wiki, takim jak Confluence lub MediaWiki, można:

• Utwórz artykuł dla każdego terminu.
• Zdefiniuj wspólną strukturę artykułów w niektórych szablonach, aby zawierały one wspólne sekcje, które można wykorzystać do agregacji.
• Z łatwością dodawaj linki do definicji terminów w innych artykułach wiki.
• Twórz tabele agregatów z definicjami terminów i osadzaj je w innej dokumentacji.

Obecnie używam Confluence do dokumentowania architektury informacji, której częścią są wszechobecne definicje języków. Najwyższym poziomem tej dokumentacji są artykuły z domeny. W każdej aplikacji istnieje wiele domen, np. Bezpieczeństwo, płatności itp. Domeny te są zdefiniowane przez szereg interakcji użytkownika z systemem, które można opisać za pomocą wszechobecnego języka, dlatego umieszczam definicje tych interakcji na osobnych podstronach i definicje terminów wprowadzonych przez te interakcje na podstronach stron interakcji. Umieszczam tabele agregacji na stronach nadrzędnych, aby można było na przykład zobaczyć, które scenariusze składają się na domenę i jakie terminy są w niej zdefiniowane.

Kiedy ta struktura dokumentacji jest gotowa i przechodzę do bardziej szczegółowych specyfikacji systemu, mogę po prostu odnieść się do definicji IA i UL scenariuszy, np. „Komponent A wdraża integrację z systemem B w celu obsługi interakcji C (link scenariusza IA), przekazując informacje o Z (łącze UL) ”.