Перейти к основному содержимому

Руководство по написанию документации

Правила и рекомендации по ведению технической документации в Docusaurus для микросервисов Talent Platform.

Язык и стиль​

  • Язык: русский.
  • Стиль: профессиональный, enterprise, без эмодзи.
  • Тон: нейтральный, информативный.

Структура документа​

Рекомендуемая последовательность разделов:

  1. Назначение — краткое описание цели и контекста.
  2. Цель (опционально) — перечисление целей.
  3. Входные данные / Message Contract / Структура — таблицы с полями, типами, ограничениями.
  4. Бизнес-логика — основной сценарий, альтернативные сценарии.
  5. Диаграмма алгоритма — Mermaid flowchart или sequence.
  6. Связанные разделы — ссылки на связанные сущности, команды, API.

Форматирование​

Таблицы​

Используйте Markdown-таблицы для схем, payload, полей:

| Поле | Тип | Обязательное | Описание |
|------|-----|--------------|----------|
| Id | Guid | Да | Идентификатор |

Admonitions​

  • :::note — примечания.
  • :::tip — подсказки.
  • :::warning — предупреждения.
  • :::danger — критические замечания.
  • :::info — дополнительная информация.

Mermaid​

Поддерживаются flowchart, sequenceDiagram, erDiagram. Проверяйте синтаксис (camelCase для ID, кавычки для меток со спецсимволами).

Именование​

  • C#-сущности: PascalCase (UserEntity, CreateUserCommand).
  • Файлы и URL: kebab-case (user-entity.md, create-user-command.md).
  • Заголовки: заглавная буква, без точки в конце.

Связи между документами​

Используйте относительные или абсолютные ссылки:

[UserEntity](/identity/database/entities/user)
[AddUserContactCommand](/identity/domain/partners/add-user-contact)

Шаблоны​

  • API-метод: HTTP-метод, путь, входные данные, результат, CQRS-связи.
  • Entity: структура таблицы, ограничения, индексы, связанные сущности.
  • Kafka Event: Message Contract, топик, вложенные модели, бизнес-правила.
  • Saga: триггеры, шаги, payload, handlers.

Добавление нового микросервиса​

  1. Создать docs/identity/-подобную структуру в docs/{service}/. Пример группы сервисов: Chessboard с подсервисом Chessboard.Panoramas.
  2. Добавить секции в sidebars.ts.
  3. Обновить docs/intro.md со ссылкой на новый микросервис.