Як документувати всюдисущу мову?

Наша компанія перетворює багато ручних бізнес-процесів (та пов'язаних з ними інституційних знань) у нове програмне забезпечення для підприємства. Проект іде дуже добре, але, як ми продовжуємо, зрозуміло, що існує багато плутанини щодо термінів та визначень як з боку бізнесу, так і з боку розвитку.

Я деякий час знав аргументи Евана щодо формування всюдисущої мови, але це вперше мені потрібно офіційно їх документувати. Коли я оглядаюсь і намагаюся думати про те, де / як задокументувати наші умови UL, я якось загубився.

Як інші компанії документують всюдисущу мову? Це лише словник у стилі вікі? Чи є якийсь інструмент, призначений для цієї мети?

Ви можете ставитися до "всюдисущої мовної документації" як до проекту з налаштування програмного забезпечення: вам потрібно взяти деяке програмне забезпечення для управління документацією та адаптувати його до ваших конкретних потреб. У програмних проектах ви зазвичай починаєте зі збирання потреб користувачів, потім будуєте інформаційну архітектуру та дизайнерське рішення, а потім приступаєте до впровадження. Нижче наводиться приклад цього процесу.

Які потреби для цього потрібні користувачеві? У деяких організаціях люди з різними функціями з різних областей хочуть використовувати загальний мовний діалект для опису своїх проблем та рішень. Цей діалект визначатиметься виключно його словниковим запасом (словами та фігурами мови), оскільки вимова тут, мабуть, не важлива, а граматика базуватиметься на літературній формі мови. Щоб документувати діалект, потрібно розробити структуру документації, яка найкраще підходить для управління словниковим словом (словник термінів).

Люди можуть захотіти скористатися цією документацією для вивчення значення слова чи абревіатури, щоб знайти правильне слово за його синонімом чи визначенням або вивчити всі слова, що складають домен.

Для цих потреб користувачів wiki - це справді хороший вибір. Як воно підходить? У такій гарній системі wiki, як Confluence або MediaWiki можна:

• Створіть статтю для кожного терміну.
• Визначте загальну структуру статей у деякому шаблоні, щоб вони містили деякі загальні розділи, які можна використовувати для агрегування.
• Легко додайте посилання на визначення термінів в інших статтях вікі.
• Побудуйте сукупні таблиці з визначеннями термінів і вставте їх в іншу документацію.

В даний час я використовую Confluence для документування інформаційної архітектури, а також визначення всюдисущої мови є її частиною. Найвищий рівень цієї документації - статті домену. У кожному застосуванні є кілька доменів, наприклад, безпека, платежі тощо. Ці домени визначаються рядом взаємодій користувача з системою, які можна описати всюдисущим мовою, тому я визначаю ці взаємодії в окремі підсторінки та визначення термінів, введених цими взаємодіями на підсторінках сторінок взаємодії. Я розміщую сукупні таблиці на батьківських сторінках, щоб можна було побачити, наприклад, з яких сценаріїв складається домен і які терміни визначені в ньому.

Коли ця структура документації виконана, і я перейду до більш детальних специфікацій системи, я можу просто посилатися на визначення IA та UL сценаріїв, наприклад "компонент A реалізує інтеграцію з системою B для підтримки взаємодії C (посилання сценарію IA), передаючи інформацію про Z (посилання UL) ".