Я из команды технических писателей VK WorkSpace и один из авторов порталов документации:  https://biz.mail.ru/docs/on-premises/.

На докладе расскажу, как мы решили проблему единого источника с помощью связки трех инструментов: MkDocs + Jinja2 + GitLab.

У нас есть 2 проекта, документация к которым совпадает на 90%. Поддержка разницы в 10% занимала у нашей команды половину рабочего времени одного технического писателя. Я покажу, как, с помощью единого источника, мы сократили расходы на поддержку более чем в 2 раза, и расскажу какие задачи мы решали.

• Покажу как выглядят исходные документы (на Jinja), и как они подключаются в выходные документы(на Markdown).
• Как исключать и добавлять контент для разных заказчиков.
• Что делать, если релизы у заказчиков выходят в разное время.
• Как менять уровни заголовков, если нужна отдельная инструкция и большой документ.

• Как настроить среду разработки для работы с Jinja.
• Поделюсь GitLab CI для передачи исходных документов между репозиториями.

Я из команды технических писателей VK WorkSpace и один из авторов портала документации:  https://biz.mail.ru/docs/on-premises/.

Расскажу, как любому техническому писателю можно перейти на подход docs-as-code и запустить веб-портал с документацией без помощи dev-ops'ов и разработчиков. Мы пройдем следующий путь:

1. Создадим свой первый портал с помощью языка Markdown и движка MkDocs.
2. Подключим популярную тему Material и кастомизируем портал: перекрасим в корпоративные цвета, заменим лого, подключим различные плагины и расширения.
3. Сложим весь результат нашей работы на Git.
4. С помощью GitHub Actions настроим деплой нашего портала в GitHub Pages и автоматизируем выкладку обновлений.

Перед мастер-классом:

1. Заведите аккаунт на GitHub.

2. Установите Git: git-scm.com/download

3. Установите Python: www.python.org/downloads