Docs as code на пальцах

Обо мне

• 15 лет в IT (web). Прошел путь fullstack, teamlead
• Работаю CTO в Вебпрактик (130 человек)
• Пишу на нескольких языках программирования
• Влюблен в Linux, OpenSource
• Организатор Ростовского PHP сообщества (~400 человек)
• Член программного комитета TechLeadConf, CTOconf, Podlodka Crew

План доклада

1. Что такое docs as code
2. Как мы к этому пришли
3. Основные плюсы и минусы подхода
4. В процессе сравниваем с confluence
5. Выводы

В чем вы пишете документацию?

1. confluence
2. google docs / word
3. notion
4. российские аналоги

Кто слышал
о DOCS AS CODE подходе?

А кто пробовал?

Docs as code

Это значит применять к документации все те же правила, инструменты и процедуры, что и к программному коду.

Например:

• хранить исходники в репозитории
• использовать CI для сборки документации
• использовать MR для ревью
• пропускать автотесты

Как мы пришли к docs as code

Особенности работы с крупным аутсорсом

• Крупные проекты мигрируют между крупными игроками (тендеры)
• Уровень отношения к документации разный:
  • Документации нет
  • Документация передается вордовским файлом
  • В лучшем случае бекап конфлюенса
• Даже если есть — почти всегда отрывочная, неполная
• Онбординг в проект: много реверса документации аналитиками и техлидами

Путь

1. Разрозненные google docs
2. Были простые вики (2 вида) с wysiwyg редактором (self hosted)
3. Техлиды и разработчики системно не любили в них ходить
4. "техн. документация должна лежать как можно ближе к коду"
5. Начинали с простого markdown в репозитории проектов
6. Со временем доросли до статических генераторов (mkdocs)
7. Переехали на facebook docusaurus
8. В некоторых проектах начали выносить в отдельные репозитории
9. Построили внутреннюю документацию всей компании на docusaurus

Как сейчас

1. Внутреннюю базу знаний компании перевели на другой open source инструмент т.к. ей пользуются не только отдел разработки
2. На многих проектах клиентов используем docs as code

Какие фишки и преимущества дает Docs-as-Code подход?

Версионирование документации

• Не линейное в отличие от confluence
• Патчи затрагивающие сразу много документов
• Стандартизированные комментарии версий
• Суммарные диффы
• Возможность показать сразу 2 версии (старая и новая)
• Переиспользование блоков документации

Удобные комментарии

• Их нельзя случайно удалить
• Они сильно функциональнее чем в confluence
• Можно прокомментировать каждую строчку изменения

Понимание кто когда и почему изменил каждую строчку

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

• Можно назначить нескольких ревьюеров
• Автоматическая проверка качества
• Комментарии и голосования
• flow согласования

Контроль и повышение качества документации

• Помимо Ревью
• Множество фич статического анализа:
  • Автоматическая проверка качества (наличия!) и стандарта комментария изменения
  • Проверка правил форматирования
  • Проверка орфографии
  • Проверка ссылок (битая ссылка не пройдет)

Стандарт комментариев измнений

        docs(catalog): добавлено описание каталога
        fix(catalog): исправлена ошибка
        style(catalog): скорректировано оформление
        refactor(catalog): обновлено описание
    

Интеграция с тасктрекером

• Подгрузка коммитов с документацией в таску
• достаточно лишь упомянуть ее в коммите изменения

self hosted документация

📦 Необходимость отчуждения документации

📝 Удобный редактор

• Ни 1 web wysiwyg редактор не сравнится по качеству работы с текстом с IDE
• Множественные курсоры
• Множественное изменение текста внутри файла
• Пакетные изменения файлов
• Поиск и замена с регулярными выражениями
• Локальная история изменений
• Куча shortcat на все случаи жизни
• МНОЖЕСТВО других фич

😊 Остальные возможности IDE

• Если вы работаете с базами данных
• Git
• HTTP запросы
• SSH
• SFTP
• Docker

Управление знаниями с использованием процессов, знакомых инженерам

Схемы и диаграммы как код

• plantuml
• mermaid
• kroki
• другие

, integration

Как это работает
и какие инструменты ⚒️

Система контроля версий

• gitlab
• github
• bitbucket
• other

Язык разметки

• markdown
• rst
• asciidoc

⚙️ Движок визуализации

• Docusaurus
• mcdoc
• gitbook
• jekill
• yandex diplodoc
• writeside?
• и др

⚙️ Зачем нужен движок

Facebook Docusaurus

Github 48 000 🌟

Docusaurus
+

А нужно ли
это мне?

Недостатки

1. Более высокий уровень входа (git + markdown)
2. Скорость внесения изменения ниже
3. Разграничение прав доступа
4. Таблицы (markdown vs asciidoctor)

🧐 Когда можно подумать

• Вы переходите с неспециализированных инструментов
• Или планируете уйти с confluence
• Вам нужен selfhosted / opensource
• Большая часть контрибьютеров и потребителей документации - технари
• Вам нужен высокий уровень контроля качества документации
• У вас сложный флоу согласования
• У вас публичная документация

✋ Когда не стоит

• Сложные многоуровневые права доступа к каждому документу
• Документацией владеют больше не технические специалисты
• Всю вашу команду более чем устраивает confluence и вы не упираетесь в него
• Вы пользуетесь инструментами вроде requirement yogi

Если хотите попробовать:

• Убедитесь что собрали боли
• Убедитесь что донесли все плюсы и минусы этого подхода и для команды плюсы перевесили

Выводы

• Docs as Code прекрасный подход дающий огромный багаж возможностей
• Может закрыть потребности многих технических команд и вывести их на новый уровень работы с документацией
• Но подойдет не каждой команде
• Он отлично заходит в outsource для крупного бизнеса

Полезные ссылки

• markdown
• docusaurus
• diplodoc
• writeside(лучше!) или vscode