Порядок обновления и публикации документации

Дата: 2026-02-10
Цель: Определить последовательность обновления документов и их публикации на docs.cdto.life.

1. Принципы

  • Единый источник правды: основная структура задаётся PROJECT-SECTIONS.md (11 разделов по логической структуре).
  • Оглавление и навигация (INDEX.md, NAVIGATION.md) должны соответствовать этой структуре.
  • База знаний (AI-KNOWLEDGE-BASE.md) и её HTML-версия обновляются при изменении содержания или структуры разделов.
  • Публикация выполняется после коммита в репозиторий (синхронизация на docs.cdto.life — по таймеру или вручную).

2. Порядок обновления при изменении логической структуры

Шаг Действие Файлы
1 Зафиксировать структуру разделов docs/PROJECT-SECTIONS.md
2 Обновить оглавление docs/INDEX.md — разделы и ссылки по новой структуре
3 Обновить навигацию docs/NAVIGATION.md — те же 11 разделов и подразделы
4 Обновить базу знаний docs/AI-KNOWLEDGE-BASE.md — блок «Соответствие разделам проекта», навигация по категориям
5 Перегенерировать HTML базы знаний Запуск python3 /home/cdto/DENKART/tools/generate-knowledge-base-html.py → создаётся docs/knowledge-base.html (Bootstrap-навигация)
6 Проверить ссылки В INDEX, NAVIGATION, PROJECT-SECTIONS — битые ссылки и пути
7 Закоммитить и при необходимости синхронизировать Git commit; при необходимости — ручная синхронизация на docs.cdto.life

3. Порядок обновления при добавлении нового контента

Ситуация Действия
Новый документ в существующем разделе Добавить ссылку в INDEX.md и NAVIGATION.md в нужный раздел (2–11). При необходимости — в PROJECT-SECTIONS.md (описание содержания).
Новая запись в базе знаний Добавить запись в AI-KNOWLEDGE-BASE.md по шаблону; запустить tools/generate-knowledge-base-html.py для обновления knowledge-base.html.
Изменение только текста документа Править только сам документ. INDEX/NAVIGATION не трогать, если заголовок/раздел не менялся.
Новый раздел или переименование Сначала обновить PROJECT-SECTIONS.md, затем INDEX.md, NAVIGATION.md, при необходимости AI-KNOWLEDGE-BASE.md и порядок публикации (этот документ).

4. Публикация на docs.cdto.life

Способ Когда использовать
Автоматическая (таймер) Каждые 5 минут проверяются изменения в docs/; при наличии — синхронизация в контейнер docs-denkart.
Ручная Сразу после важных правок: sudo /home/cdto/DENKART/scripts/sync-docs-to-web.sh или sudo systemctl start docs-sync.service.
После коммита Post-commit hook напоминает о синхронизации; фактическая выгрузка — по таймеру или вручную (см. Автоматическая синхронизация документации).

Важно: Перед публикацией убедиться, что сгенерирован актуальный docs/knowledge-base.html, если менялась база знаний.

4.1 Публикация «Инструкции по подключению BigBlueButton к Moodle» на портал Академии CDTO (lms.cdto.life)

Соответствует разделу 2.4 PROJECT-SECTIONS (рабочая документация и настройка).

Инструкция moodle-bigbluebutton-connection-instruction.md обязательна к публикации на портале Академии CDTO (https://lms.cdto.life). Полный порядок: Размещение материалов на Moodle Академия CDTO, п. 2.4.

Шаг Действие
1 Убедиться, что в Moodle создан курс «Академия CDTO» (или эквивалент)
2 Войти на https://lms.cdto.life под учётной записью Администратор / Менеджер / Преподаватель
3 Открыть курс «Академия CDTO», включить Режим редактирования
4 Добавить элемент → Страница (или Файл — PDF)
5 Название: «Инструкция по подключению BigBlueButton к Moodle»
6 Содержимое: скопировать из docs/setup/moodle-bigbluebutton-connection-instruction.md (конвертировать Markdown в HTML при необходимости)
7 Сохранить, выключить режим редактирования
8 Проверка: открыть страницу по URL (выводится скриптом)
9 Сравнительный анализ: реальная публикация vs заданное содержимое (заголовки, шаги, ссылки, форматирование)
10 SEO: проверить ключевые фразы, заголовки, мета-теги — python3 scripts/verify-moodle-page-seo.py URL (автологин: config/secrets или контейнер). См. moodle-seo-and-indexing.md

Автоматизация: scripts/publish-bbb-instruction-to-moodle.sh. Выполнить: ./scripts/publish-bbb-instruction-to-moodle.sh (при необходимости — с --update). Обновление — только после полного анализа достоверности и полезности улучшения наполнения по теме. См. скрипт и moodle-academy-publication-and-theme.md.

5. Чек-лист перед коммитом изменений документации

  • [ ] PROJECT-SECTIONS.md актуален (при изменении структуры)
  • [ ] INDEX.md и NAVIGATION.md соответствуют PROJECT-SECTIONS и не содержат битых ссылок
  • [ ] AI-KNOWLEDGE-BASE.md обновлена при новых ошибках/решениях или смене разделов
  • [ ] Выполнен python3 tools/generate-knowledge-base-html.py при изменении AI-KNOWLEDGE-BASE.md
  • [ ] CHANGELOG.md при необходимости обновлён (крупные структурные изменения)
  • [ ] Инструкция BBB→Moodle опубликована на lms.cdto.life (при добавлении/обновлении инструкции) — п. 4.1, скрипт publish-bbb-instruction-to-moodle.sh
  • [ ] Проверка по URL выполнена, сравнительный анализ (реальная публикация vs заданное) пройден
  • [ ] SEO проверен (ключевые фразы, мета-теги, индексация); robots.txt при необходимости развёрнут — ./scripts/setup-moodle-robots.sh

6. Связанные документы

Документ подготовлен: AI Denkart, технический директор проекта DENKART (порядок обновления и публикации — 2026-02-10).