Skip to main content
✱ Подходы, инструменты, стандарты

Есть только путь до single-source

Techwriter Days #2
2025-03-28 14:00
Секция B
40 мин
Просто
Доклад был на прошедшей конференции Techwriter Days #2 и сейчас находится в архиве.
На конференции Techwriter Days 2 у нас был замечательный доклад, который не оставил равнодушными любителей технической документации. Никита Груздев поделился своим опытом и подробно рассказал о пути к принципу единого источника. Этот доклад открывает двери в мир оптимизации управления содержимым, позволяя использовать единый контент в различных форматах и документах. Никита начал с личной истории: он работает в ВК Workspace и преподаёт математику в Омске. Его опыт в построении первого портала для продуктов компании вдохновил многих на конференции. Центральной темой его выступления был переход от копирования и вставки документации к более современной системе с использованием единого источника. Это решение позволяет избежать бесконечного копирования изменений и значительно упрощает процесс обновления информации для разных клиентов. Главным вызовом, с которым столкнулась команда Никиты, было управление документами для разных заказчиков с разными требованиями. С помощью мощных инструментов и подходов, таких как MKDS и Ginja 2, удалось автоматизировать и упростить этот процесс, сохранив актуальность контента во всех выходных документах. Благодаря внедрению этой системы улучшилась не только точность, но и повысилась эффективность всей команды. Полезный урок в том, что новшества могут сделать работу более интересной и продуктивной.
Я из команды технических писателей VK WorkSpace и один из авторов порталов документации: https://biz.mail.ru/docs/on-premises/. На докладе расскажу, как мы решили проблему единого источника с помощью связки трех инструментов: MkDocs + Jinja2 + GitLab. У нас есть 2 проекта, документация к которым совпадает на 90%. Поддержка разницы в 10% занимала у нашей команды половину рабочего времени одного технического писателя. Я покажу, как, с помощью единого источника, мы сократили расходы на поддержку более чем в 2 раза, и расскажу какие задачи мы решали. Покажу как выглядят исходные документы (на Jinja), и как они подключаются в выходные документы(на Markdown). Как исключать и добавлять контент для разных заказчиков. Что делать, если релизы у заказчиков выходят в разное время. Как менять уровни заголовков, если нужна отдельная инструкция и большой документ. Как настроить среду разработки для работы с Jinja. Поделюсь GitLab CI для передачи исходных документов между репозиториями.

Доступно только после покупки 😊

Другие доклады Techwriter Days #2