How to Use & Contribute

Концепция управления документацией проекта SEAF. #

Разработана концепция управления документацией SEAF с использованием двух методологических подходов:

  • “docs as code” (“документация как код”) и
  • Zettelkasten, - в совокупности обеспечивающих проект SEAF возможностями интеллектуального управления идеями и документацией, создания контента для публикации на научных, технологических, развлекательных и любых других площадках.

С помощью выбранного подхода и современных поддерживающих его инструментов (Obsidian, плагины IDE, Hugo) реализуется “воронка”/“pipeline” для AI-native управления знаниями от идеи до реализации в инструменте.

Правовые основы #

  1. Общие правовые основания появления, использование и развития SEAF Base Of Knowledge (SEAF BOK) физическими и юридическими лицами изложены в SEAF On A Page.
  2. Требования к разметке кода и контента для целей соблюдения требований авторского и исключительного права изложены в Как разметить статью или исходный код
  3. Список контрибьюторов SEAF BOK постоянно пополняется новыми участниками.

Подход Docs as Code: сущность и преимущества #

Подход Docs as Code представляет собой методологию разработки программной документации с использованием тех же инструментов и процессов, что применяются для написания кода.

Ключевые компоненты подхода Docs as Code:

  • Использование упрощенных языков разметки (Markdown, reStructuredText, Asciidoc)
  • Хранение документации в репозиториях Git
  • Сборка публикуемой документации с помощью генераторов статических сайтов
  • Применение CI/CD для автоматизации публикации

Основные преимущества данного подхода для проекта SEAF:

  • Вовлеченность разработчиков: использование знакомых инструментов повышает желание участвовать в создании документации
  • Версионность: контроль изменений документации аналогично контролю кода
  • Автоматизация: непрерывная интеграция обеспечивает актуальность документации
  • Простота публикации: автоматическое обновление веб-сайта при обновлении репозитория GIT
  • Экономичность: использование общедоступных инструментов снижает стоимость1

Подход Zettelkasten для управления знаниями: сущность и преимущества #

Ключевые принципы Zettelkasten для SEAF: #

  • Атомарность: каждая заметка содержит только одну архитектурную концепцию или паттерн

  • Автономность: заметки самодостаточны и понятны без контекста

  • Связанность: создание явных связей между архитектурными концепциями

  • Уникальная идентификация: каждый элемент фреймворка имеет свой ID

  • Пояснение связей: объяснение логического обоснования связей между концепциями2

    Практическая реализация в контексте SEAF #

Для SEAF рекомендуется создание двух основных информационных графов:

  1. SEAF Fundamentals: базовые концепции, принципы и модели архитектуры
  2. SEAF Guides: практические руководства, примеры применения, шаблоны

Структура заметки должна включать:

  • Уникальный идентификатор
  • Название концепции/принципа
  • Краткое описание (2-3 предложения)
  • Подробное объяснение
  • Ссылки на связанные концепции
  • Метаданные (дата создания, автор, теги)3

Архитектура репозитория SEAF-BOK #

Для оптимальной организации документации SEAF предлагается федеративная модель с использованием Git submodules.

Федеративная модель документации #

Структура документации SEAF, включая SEAF Fundamentals и SEAF Guides, изложенная в составе SEAF On A Page: Структура документации SEAF

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


seaf-bok (основной репозиторий)
├── fundamentals (подмодуль -> seaf-fundamentals)
├── guides (подмодуль -> seaf-guides)
├── scripts (скрипты сборки и публикации)
├── themes (темы для статического сайта)
└── docs (сгенерированная документация для GitHub Pages)

Использование Git Submodules #

Git submodules позволяют включать один репозиторий внутрь другого, сохраняя независимость истории изменений. Для SEAF-BOK этот подход обеспечивает:

  1. Модульность: независимое развитие компонентов SEAF

  2. Контроль версий: фиксация определенных версий документации

  3. Управляемость: централизованный доступ через основной репозиторий5

Пример команд для настройки:


# Создание основного репозитория
mkdir seaf-bok
cd seaf-bok
git init
git remote add origin https://github.com/организация/seaf-bok.git

# Добавление подмодулей
git submodule add https://github.com/организация/seaf-fundamentals.git fundamentals
git submodule add https://github.com/организация/seaf-guides.git guides

Технические основания разработки SEAF BOK: #

  1. Процесс распределенной разработки SEAF с помощью публичного сервиса GitHub. GitHub Pages для документации SEAF. Короткие доменные имена.
  2. Целевой репозиторий SEAF BOK и процесс распределенной разработки через форки
  3. Что такое и зачем нужен Hugo
  4. Процесс публикации документации SEAF Base Of Knowledge
  5. Статусы заметок/документов: черновики и готовые к релизу. Где документы хранятся и как публикуются. Управление статусами любого артефакта в составе документации: страницы, изображения, любого другого ресурса страницы и т.д.
  6. Теги заметок/документов. Принципы их ведения и набор

Инструмент для генерации сайта #

Для создания сайта SEAF (https://seaf.sci.community) используется Hugo по следующим причинам:

  • Высокая скорость: генерация сайта из 2700 страниц за 500 мс (в сравнении с 90 секундами у Jekyll)
  • Гибкость шаблонов: использование мощного языка Go для создания динамических шаблонов
  • Поддержка от Google: активное развитие и поддержка сообщества
  • Наличие тем для документации: специализированные темы Docsy, Learn и др.6 Для создания прототипа выбрана тема Book.

GitHub поддерживает HUGO через стандартные actions и проводит мониторинг как они работают в связке: https://jmooring.github.io/hugo-sites/, что делает инструмент легкодоступным сейчас и в будущем.

В Hugo и GitHub используют такие компании и проекты, как:

  1. https://docs.ozon.ru/main/ (описание подхода к формированию документации доступно https://habr.com/ru/companies/ozontech/articles/695868/)
  2. https://kubernetes.io/ (репозиторий https://github.com/kubernetes/website)
  3. https://www.freebsd.org/
  4. https://docs.docker.com/get-started/docker-overview/
  5. https://gohugo.io/documentation/

Настройка публикации на GitHub Pages #

Для настройки публикации на GitHub Pages настроен GitHub Actions** - рабочий процесс, который запускается при обновлении ветки master репозитория

Хранение медиафайлов Drawio #

В репозитории хранятся исходные файлы в формате drawio для статических изображений. В репозитории содержится папка .obsidian, содержащая файлы установленного плагина и его настройки (их изменять не требуется). Рекомендуется использовать плагин Diagrams Сообщества Obsidian .

Хранение медиафайлов Excalidraw #

В репозитории хранятся исходные файлы в формате excalidraw для статических изображений. Методика работы excalidraw, плагином в Obsidian подробно описана здесь. В репозитории содержится папка .obsidian, содержащая файлы установленного плагина и его настройки. Рекомендуется использовать плагин Excalidraw Сообщества Obsidian .

Сравнительный анализ инструментов для работы с документацией #

IDE и расширения для работы с Zettelkasten #

IntelliJ IDEA #

Markdown Navigator - наиболее функциональный плагин для IntelliJ IDEA:

  • Поддержка markdown с предпросмотром

  • Интеграция с GitHub Wiki

  • Навигация по ссылкам между заметками

  • Поддержка TODO в markdown-комментариях78

    Преимущества IntelliJ IDEA для SEAF:

  • Мощная интеграция с системами контроля версий

  • Высокая функциональность для автодополнения и рефакторинга

  • Поддержка множества языков программирования9

Visual Studio Code #

Наиболее подходящие расширения для Zettelkasten в VSCode:

  • Foam: лучше всего работает с связанными заголовками и инлайн-ссылками

  • Dendron: мощная иерархическая система заметок, но требует отдельного рабочего пространства

  • Markdown Memo: хорошо справляется с связанными секциями и двунаправленными ссылками10

Преимущества VSCode для SEAF:

  • Легковесность и быстрота работы
  • Большое количество расширений
  • Простота настройки предпросмотра Markdown с разными темами911

Zed #

Встроенные возможности Zed для работы с Markdown:

  • Подсветка синтаксиса с использованием tree-sitter

  • Языково-специфическая подсветка кода в блоках

  • Интеграция с Prettier для форматирования

  • Настраиваемые параметры обработки пробелов12

Преимущества Zed:

  • Высокая производительность при работе с большими документами

  • Интеграция с AI для генерации и анализа документации

  • Встроенные функции коллаборации для команды SEAF

Рекомендуемый набор инструментов для команды SEAF #

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

  1. VSCode с расширением Foam как основной редактор для большинства участников:

    - Наилучший баланс между функциональностью и простотой

    - Хорошая поддержка методологии Zettelkasten

    - Легковесность и быстрота работы

  1. IntelliJ IDEA с Markdown Navigator для технических писателей и руководителей проекта:

    - Мощные возможности рефакторинга

    - Глубокая интеграция с Git

    - Управление проектами в одном интерфейсе

Процесс квартальных релизов документации #

Для обеспечения регулярных квартальных релизов документации SEAF рекомендуется следующий процесс:

Планирование и подготовка релиза #

  1. Установка четкого графика релизов:

    - Фиксированные даты релизов (например, первый день каждого квартала)

    - Разделение процесса на фазы (планирование, разработка, тестирование, публикация)

    - Выделение буферного времени для непредвиденных задержек13

  1. Процесс обновления документации:

    - Создание веток для новых версий документации

    - Разработка новых материалов в ветках feature/

    - Code review изменений в документации

    - Слияние изменений в основную ветку перед релизом

Автоматизация релизов #

  1. Использование тегов Git для версионирования:

    - Создание тегов для каждого квартального релиза (например, v2025-Q1)

    - Обновление подмодулей до соответствующих тегов

  1. CI/CD для автоматизации публикации:

    - Настройка GitHub Actions для автоматической сборки и публикации

    - Генерация примечаний к релизу (release notes)

    - Автоматическое обновление версии на сайте13

Документирование процесса релиза #

Для каждого релиза необходимо:

  • Вести журнал изменений (CHANGELOG.md)

  • Создавать документацию по миграции между версиями

  • Сохранять историю предыдущих версий документации

Примеры успешных проектов с подходом docs as code #

Архитектурная документация с arc42 и C4 Model #

Проект milanm/architecture-docs демонстрирует генерацию архитектурной документации с использованием шаблона arc42, модели C4, Structurizr CLI и Asciidoctor. Данный подход может быть адаптирован для визуализации архитектурных концепций SEAF14.

OpenTelemetry #

OpenTelemetry использует федеративную модель документации, где центральный репозиторий документации импортирует контент из репозиториев кода с использованием git submodules. Этот подход особенно ценен для проектов с автономными компонентами, как в случае с SEAF4.

Документация как сервис #

Пример рабочего процесса, где CI/CD конвейеры генерируют исходники документации и публикуют их, используя отдельный репозиторий-сателлит. Это позволяет разделить контент и представление документации, что ценно для SEAF с его разделением на Fundamentals и Guides15.

Заключение и рекомендации #

На основе проведенного исследования для управления документацией проекта SEAF рекомендуется:

  1. Архитектура документации:

    - Федеративная модель с использованием Git submodules

    - Разделение на репозитории SEAF Fundamentals и SEAF Guides

    - Контроль доступа на уровне организации GitHub

  1. Методология и инструменты:

    - Zettelkasten для организации связанных архитектурных знаний

    - VSCode с Foam для большинства участников команды

    - IntelliJ IDEA с Markdown Navigator для продвинутых пользователей

  1. Публикация и релизы:

    - Hugo для генерации статического сайта

    - GitHub Actions для автоматизации процесса публикации

    - Квартальные релизы с использованием тегов Git и автоматизации

Такой подход обеспечит эффективное управление документацией SEAF, сочетая преимущества docs as code с методологией Zettelkasten для создания взаимосвязанной базы знаний архитектурного фреймворка.

  1. Как документация создавалась Что такое и зачем нужен Obsidian Что такое и зачем нужен Zettelcasten

Другие расширения в IDE для создания документации в obsidian style.То есть Obsidian не является чем-то обязательным. Просто удобным, как опция для работы Поклонники Zettelcasten среди нас

Релевантные статьи:

  1. Как начать пользоваться SEAF BOK
  2. Как оформить статью SEAF BOK
  3. Как добавить статью SEAF BOK
  4. Актуальные задачи
  5. Система тегов

Включить контент:

Как начать пользоваться SEAF BOK

todolist

Концепция DocsAsCode

todolist

  1. https://progdoc.ru/news/dokumentatsiya-kak-kod-docs-as-code/ ↩︎

  2. https://dzen.ru/a/YCJHa9HQGgz4yin8 ↩︎

  3. https://www.youtube.com/watch?v=jbvEJvTwllk ↩︎

  4. https://passo.uno/docs-as-code-topologies/ ↩︎ ↩︎

  5. https://thebottleneckdev.com/blog/monorepo-git-submodules ↩︎

  6. https://idratherbewriting.com/learnapidoc/pubapis_static_site_generators.html ↩︎

  7. https://gist.github.com/maenujem/f9dce9d1eec42696643658bc7d93dd93 ↩︎

  8. https://github.com/vsch/idea-multimarkdown/wiki/Adding-GitHub-Wiki-to-IntelliJ-Project ↩︎

  9. https://sky.pro/wiki/javascript/luchshie-ide-dlya-razrabotki-sravnenie-i-vybor/ ↩︎ ↩︎

  10. https://www.reddit.com/r/Zettelkasten/comments/1044bb1/best_obsidianlike_extensions_for_vscode/ ↩︎

  11. https://stackoverflow.com/questions/55180020/set-background-color-on-visual-studio-code-markdown-preview ↩︎

  12. https://zed.dev/docs/languages/markdown ↩︎

  13. https://zeet.co/blog/software-release-management-best-practices ↩︎ ↩︎

  14. https://github.com/milanm/architecture-docs ↩︎

  15. https://habr.com/ru/companies/yadro/articles/785766/ ↩︎