Hexagonal Service Documentation Writing

Координация документации сервиса

Собирать требования к сервису и организовывать связанную документацию его бизнес-контекстов и архитектурных слоёв. Считать ответы аналитика источником требований; существующий репозиторий использовать только как пример оформления, если пользователь явно не назначил его стандартом.

Содержание

• Архитектурные границы
• Владение контрактами и зависимости документов
• Статус сведений
• Рабочий процесс
• Структура и навигация
• Владение событиями
• Документация адаптеров
• Готовность комплекта
• Открытые вопросы
• Ограничения
• Проверка

Архитектурные границы

Разделять ответственность domain-, application-, presentation- и infrastructure-слоёв. Координатор определяет необходимый состав документов и связи между ними, но не проектирует подробные контракты отдельного слоя вместо соответствующего специализированного навыка.

Соблюдать направленные внутрь зависимости:

• domain-слой не знает об application, infrastructure и presentation;
• application-слой использует domain и объявляет необходимые ему порты;
• presentation и другие входящие адаптеры преобразуют внешний контракт во входной application-контракт;
• исходящие адаптеры реализуют порты, объявленные внутренними слоями;
• infrastructure предоставляет технические механизмы адаптерам, но не становится владельцем бизнес-контрактов;
• внутренний слой не использует структуры, ошибки или интерфейсы внешнего слоя.

Владение контрактами и зависимости документов

Документация должна следовать тому же направлению зависимостей, что и код. Документ внешнего слоя может ссылаться на публичный контракт внутреннего слоя и использовать его без повторного определения. Документ внутреннего слоя не должен зависеть от документов и структур внешнего слоя.

При различии структур внешний документ описывает явное преобразование. Специфичные для транспорта, хранения или фреймворка сведения остаются во внешнем документе и не переносятся во внутренний контракт. Совпадение полей не является основанием менять владельца структуры или копировать её в соседний слой.

Application DTO могут использоваться presentation- и другими адаптерами как публичный внутренний контракт. Собственные внешние модели адаптера преобразовывать в application DTO на внешней границе. Domain не использует DTO или ошибки application.

Использовать направление ссылок:

presentation/infrastructure → application → domain

Обзорные документы сервиса могут ссылаться на все слои для навигации и проверки согласованности, но не становятся владельцами их контрактов.

Для значимых контрактов вести карту:

Не копировать в карту состав контракта. Она показывает владение, ссылки и согласованность документов.

Если на контекст, доменный объект, событие, application-операцию, DTO, порт или внешний контракт ссылается другой документ, использовать однозначное стабильное обозначение. Не предписывать им имя класса, метода или файла. Для локального элемента без внешних ссылок отдельное обозначение не требуется.

Строить стабильное обозначение как смысловую иерархию:

<бизнес-контекст>.<архитектурный-слой>.<уточняющие-сегменты...>

Первый сегмент обозначает бизнес-контекст, второй — слой гексагональной архитектуры (domain, application, presentation или иной принятый в документации слой). Последующие сегменты уточняют категорию, подкатегорию и конкретный элемент. Не ограничивать глубину фиксированным количеством сегментов, но не добавлять уровень, который не помогает различать или понимать элементы.

Каждый сегмент должен выражать один уровень смысла. Не склеивать ресурс и действие (update_member_role) и не пропускать промежуточный ресурс между категорией и действием. Одинаковый контракт во всём комплекте имеет ровно одно обозначение независимо от имени и расположения файла. Состав сегментов задаёт владеющий профильный скил в рамках этой общей иерархии.

Использовать множественное число для категории и единственное для конкретного типа: companies.domain.projections и companies.domain.projections.user. Для более глубокой структуры допустимы, например, companies.domain.events.employee.created и companies.application.operations.commands.user.contractors.create.

Статус сведений

Использовать общую классификацию:

• подтверждённое требование — нормативная часть контракта;
• принятое проектное решение — согласованный способ выполнения требования;
• предложение — ещё не согласованный вариант;
• открытый вопрос — отсутствующее решение с указанным влиянием.

Не требовать отдельный раздел со статусами, если документ содержит только подтверждённые требования и принятые решения. Предложения и предположения явно помечать и не включать в нормативные таблицы как принятые решения.

Рабочий процесс

1. Определить цель: новый комплект документов, дополнение существующих или координация отдельной части.
2. Изучить инструкции целевого репозитория и имеющуюся документацию, не выводя из кода отсутствующие бизнес-требования.
3. Провести первичное интервью по interview-workflow.md.
4. Определить бизнес-контексты, термины, владельцев данных и связи.
5. Согласовать структуру документов по repository-structure.md, адаптируя её к репозиторию.
6. Распределить требования и документы между архитектурными слоями. Для подробного проектирования передать работу соответствующему специализированному навыку.
7. Создавать документы небольшими согласованными частями, не заполняя пробелы догадками.
8. Проверить навигацию, терминологию, владельцев контрактов, направление зависимостей и отсутствие противоречий.
9. Оценить готовность комплекта и влияние каждого открытого вопроса.

Структура и навигация

Главный скил владеет архитектурными и сквозными слотами верхнего уровня, их порядком и глобальным SUMMARY.md. Он не определяет внутреннюю структуру специализированного раздела и не зависит от перечня специализированных скилов.

Специализированный документирующий скил:

• размещает документы только внутри назначенного архитектурного слота;
• определяет внутреннюю структуру своего поддерева;
• формирует фрагмент навигации с индексным документом во главе;
• не создаёт параллельный корневой раздел и не меняет порядок соседних слотов;
• при принятой структуре репозитория встраивается в неё, сохраняя владельца документа; отклонение от канона требует отдельного согласования.

Физическую структуру определять по структуре репозитория, а глобальную навигацию — по регламенту SUMMARY.md.

Для паспорта контекста читать context-documentation.md.

Для решения о необходимости паспорта адаптера и его структуры читать adapter-passport.md.

Для подробного проектирования domain использовать ddd-domain-documentation-writing, для application — cqrs-application-documentation-writing. Входящие HTTP-контракты и потребление сообщений передавать presentation-layer-documentation-writing.

Требование к публикации результата оставлять application-документу. Исходящий внешний контракт документировать, когда публикация является требованием сервиса; наличие или перечень конкретных потребителей для этого не требуются. Не передавать проектирование исходящего контракта presentation-навыку.

Владение событиями

Domain владеет свершившимся бизнес-фактом. Application владеет необходимостью, порядком и согласованностью передачи результата наружу. Отдельный внешний документ владеет интеграционным либо транспортным контрактом и преобразованием из внутреннего представления. Presentation-навык использовать только для входящих точек взаимодействия.

Не считать доменное событие внешним контрактом автоматически. Обзорный документ связывает доменный факт, application-операцию публикации и внешний контракт, но не копирует их схемы.

Документация адаптеров

Не создавать подробный аналитический документ для каждого адаптера. Простой адаптер, который очевидно реализует порт или входной контракт, отдельного документа не требует.

Краткий паспорт адаптера создавать только при неочевидных преобразованиях, ограничениях внешней системы, классификации внешних ошибок, особых гарантиях согласованности или повторов, нескольких режимах работы либо переиспользовании несколькими операциями. Фиксировать только реализуемый порт, внешнюю систему, ссылку на нормативный контракт, значимые преобразования, ограничения, конфигурацию без секретов, наблюдаемость и открытые вопросы.

Не описывать классы, методы, клиентскую библиотеку и очевидное делегирование. Паспорт адаптера не становится владельцем application-порта или внешнего контракта. Использовать структуру и критерии готовности из adapter-passport.md.

Готовность комплекта

Считать комплект готовым к следующему этапу, когда определены контексты, владельцы данных и контрактов, направления зависимостей, документы-источники, необходимые преобразования и статус специализированных документов. Реализация или детальное проектирование слоя не должны требовать заново определять границы сервиса.

Допускать частичную готовность, если явно указаны готовые контексты, слои или контракты и их зависимости.

Открытые вопросы

Каждый содержательный документ должен завершаться разделом ## Открытые вопросы. После принятия решения переносить его в основной раздел и удалять закрытый вопрос. Для каждого вопроса указывать затронутые контексты, слои или контракты и влияние: блокирует весь комплект, отдельную часть или может быть отложен. Если нерешённых вопросов нет, сохранять раздел с текстом:

## Открытые вопросы

Открытых вопросов нет.

Ограничения

• Не восстанавливать требования из кода и не сверять их с реализацией без отдельной явной просьбы.
• Не создавать в аналитической документации разделы или отдельные документы с расхождениями целевого состояния и текущей реализации. Комплект описывает, как сервис должен быть устроен. Если пользователь отдельно просит аудит реализации, результаты выдавать как самостоятельный отчёт вне нормативного комплекта.
• Не выдавать предположение за решение аналитика.
• Не определять конкретный транспорт, хранилище, фреймворк или структуру модулей без подтверждённого требования.
• Не дублировать подробные контракты специализированных документов в паспортах и обзорных материалах.
• Сохранять минимальную связанность контекстов и явно показывать каждую зависимость.
• Писать документацию на языке, заданном пользователем или правилами репозитория.

Проверка

Перед завершением убедиться, что:

• каждый контракт определён в документе владеющего им слоя;
• ссылки между слоями направлены от внешнего документа к внутреннему;
• преобразования несовпадающих структур описаны на внешней границе;
• входящие и исходящие адаптеры не смешаны с внутренними слоями;
• доменные факты отделены от интеграционных и транспортных контрактов;
• карта контрактов содержит владельцев, источники и направления зависимостей;
• переиспользуемые контракты имеют стабильные обозначения;
• предложения и открытые вопросы отделены от нормативных требований;
• комплект не содержит сравнений с текущей реализацией и реестра её расхождений;
• отдельная документация адаптера создаётся только при доказанной необходимости;
• паспорт адаптера ссылается на внутренний и внешний контракты, не переопределяя их;
• документы доступны из принятой навигации, а относительные ссылки разрешаются;
• каждый документ расположен в слоте своего владельца, а специализированные поддеревья не создают конкурирующие корневые разделы;
• SUMMARY.md соблюдает канонический порядок, содержит каждый документ ровно один раз и не содержит отсутствующих разделов;
• термины, владельцы данных и границы контекстов согласованы;
• определена готовность комплекта и влияние открытых вопросов;
• каждый содержательный документ содержит раздел Открытые вопросы, включая формулировку Открытых вопросов нет. при отсутствии вопросов.