Вы можете рассматривать «повсеместно распространенную языковую документацию» как проект по настройке программного обеспечения: вам нужно взять некоторое программное обеспечение для управления документацией и адаптировать его к вашим конкретным потребностям. В программных проектах вы обычно начинаете со сбора потребностей пользователей, затем строите информационную архитектуру и проектное решение, а затем переходите к реализации. Ниже приведен пример этого процесса.
Что для этого нужно пользователю? В некоторых организациях люди с разными функциями из разных доменов хотят использовать общий языковой диалект для описания своих проблем и решений. Этот диалект будет определяться исключительно его словарным запасом (словами и фигурами речи), поскольку произношение, вероятно, здесь не важно, и грамматика будет основываться на литературной форме языка. Чтобы задокументировать диалект, вам необходимо разработать структуру документации, которая будет наилучшим образом подходить для управления словарем (глоссарий терминов).
Люди могут захотеть использовать эту документацию для изучения значения слова или аббревиатуры, для поиска правильного слова по его синониму или определению или для изучения всех слов, составляющих домен.
Для этих потребностей пользователей wiki - действительно хороший выбор. Как это подходит? В хорошей вики-системе, такой как Confluence или MediaWiki, можно:
- Создать статью для каждого термина.
- Определите общую структуру статей в некотором шаблоне, чтобы они содержали некоторые общие разделы, которые можно использовать для агрегирования.
- Легко добавлять ссылки на определения терминов в других статьях вики.
- Создайте сводные таблицы с определениями терминов и вставьте их в другую документацию.
В настоящее время я использую Confluence для документирования информационной архитектуры, и повсеместные определения языка являются его частью. Высшим уровнем этой документации являются предметные статьи. В каждом приложении есть несколько доменов, например, безопасность, платежи и т. Д. Эти домены определяются рядом взаимодействий пользователя с системой, которые могут быть описаны вездесущим языком, поэтому я помещаю определения этих взаимодействий в отдельные подстраницы и определения. терминов, введенных этими взаимодействиями на подстраницах страниц взаимодействия. Я разместил сводные таблицы на родительских страницах, чтобы, например, было видно, из каких сценариев состоит домен и какие термины в нем определены.
Когда эта структура документации завершена, и я перехожу к более подробным спецификациям системы, я могу просто сослаться на определения сценариев IA и UL, например, «компонент A реализует интеграцию с системой B для поддержки взаимодействия C (ссылка на сценарий IA) путем передачи информации о Z (ссылка UL) ".