Привет! Меня зовут Наталья и я DocOps-инженер в компании Yadro.

Я планирую выпустить цикл статей об этой профессии на примере Yadro. Первая статья носит обзорный характер, последующие будут более техническими и содержать примеры реальных кейсов, с которыми приходится сталкиваться во время работы.

Немного о себе

Я окончила механико-математический факультет, во время учёбы занималась матмоделированием в области авиастроения, затем семь лет работала инженером по локализации и техническим писателем в Xsolla, потом полтора года в роли руководителя команды автоматизации, и вот я DocOps в компании Yadro.

Бэкграунд

Как технический писатель: навыки документирования, Swagger, Markdown, html, JIRA, Confluence, Git.

Как локализационный инженер: плотная работа с Serge/Smartcat, Gitlab CI/CD, bash, linux

Из университета: базовые навыки разработки, матмоделирование (в котором математики намного больше, чем программирования) на С++.

DOC-инфраструктура YADRO

Стек: Исходный формат файлов — DITA, движок сборки — Oxygen Publishing Engine. В качестве системы непрерывной интеграции — Jenkins. Исходники хранятся в Bitbucket, задачи — в Jira.

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

Основные процессы

Документация разрабатывается в рамках концепции единого источника. Организована двухэтапная система проверки нового контента: peer-review и внешняя вычитка. Прежде чем новый документ будет допущен на вычитку владельцам продукта, он проходит проверку у дежурных ревьюеров. Обратная связь вне процесса вычитки доступна в виде комментариев. Для этого в приложение встроен Oxygen Feedback. Для тех, кто предпочитает править исходный текст напрямую, настроена интеграция с Oxygen WebAuthor. Дополнительно организован процесс по доставке комментариев из WebAuthor в BitBucket.

Конвейер

Исходные файлы преобразуются в HTML и/или PDF-файлы. В зависимости от режима сборки собранные файлы помещаются в одну из сред:

• Тестовый инстанс — у каждого технического писателя есть собственный инстанс приложения. Данный инстанс используется для сборки рабочих веток (мы не собираем документацию локально) и для peer-review внутри отдела.

• Тестовое окружение, предназначенное для разработки режимов сборки приложения, отладки новых интеграций и так далее.

• Стейдж — инстанс приложения, доступный для всех сотрудников компании. Используется для review владельцами продукта, а также для обкатывания новых сервисов и инструментов до публикации на проде.

• Прод — приложение, доступное внешним пользователям, содержит стабильные версии документов, прошедших внутреннее peer review и review экспертов внутри компании.

Помимо этого, развернуты вспомогательные сервисы: Oxygen Feedback, Oxygen Web Author (на  WebDAV-сервере + кастомная интеграция с Bitbucket), Serge.

Публикация

Публикация документов осуществляется отдельным приложением, написанным на Django. У приложения типовой жизненный цикл разработки с использованием CI, автотестов и прочих полезных практик разработки ПО. Приложение предназначено для гибкой и удобной публикации документов с разграничением прав доступа и формированием логической структуры документов.

Интеграция приложения и CI документации позволяет автоматически публиковать собранные документы в различных инстансах и управлять атрибутами документов: 

• со стороны технических писателей — указывая необходимые значения в конфигурационных файлах, 

• со стороны продакт-менеджмента — выставляя разрешения в административной панели.

За разработку приложения отвечает отдельная команда, работающая в плотной связке с DocOps-инженером.

Обязанности DocOps-инженера

Итак, чем занимается DocOps-инженер?

Maintenance: стабильная сборка во всех режимах, обеспечение доступности всех вспомогательных сервисов, обновление частей инфраструктуры.

R&D: реализация, изменение и оптимизация сценариев сборки, настройка CI/CD, интеграция дополнительных сервисов, кастомизация коробочных решений.

Knowledge sharing: обучение коллег работе в окружении, с новыми инструментами. Поднятие общего уровня технических скиллов в команде.

Пример задачи R&D

Запрос: приложение документации очень большое, поэтому документы собираются поштучно. Часть должна собираться пакетами: по три штуки на один продукт. Когда эти документы включили в конвейерную сборку, стало неудобно: сложно при каждой правке выбрать три нужных.

Решение: данный блок документов вынесен в отдельную структуру, для них реализован иной сценарий сборки. Теперь выбирается продукт, к нему автоматически определяется пакет необходимых документов. Таким образом, писатели избавлены от необходимости выбирать документы из большого списка, процесс сборки стал более user-friendly.

Пример задачи Knowledge sharing

Запрос: Писатели сосредоточены на разработке документации. В то же время, приложение и инфраструктура бурно развиваются. Как следствие, писателям сложно пользоваться техническими инструментами, а в случае возникновения проблем диагностировать и рапортовать о них.

Решение: запущен внутренний проект по документированию инфраструктуры, а также разработан ряд практических задач, которые позволят вживую (но в безопасном режиме) потрогать все сервисы.

Пример задачи Maintenance

Запрос: После сборки приложения не отобразились картинки. При этом, в исходных файлах пути к картинкам указаны верно, картинки загружены.

Решение: как оказалось, в названиях файлов с картинками были использованы недопустимые символы, которые в процессе сборки и публикации заменялись на пробел. Приведение вида названий файлов к внутреннему стандарту решило проблему.

Приведенные в примерах задачи достаточно просты, они не очерчивают весь круг обязанностей DocOps-инженера. К сожалению, действительно интересные кейсы требуют слишком объемного описания, и не подходят для формата обзорной статьи.

Кто может стать DocOps

DocOps-инженер — одно из возможных направлений развития карьеры технического писателя. Многим писателям приходится осваивать новые инструменты, настраивать различные интеграции, решать смежные задачи (локализацию, например). В случае смещения фокуса профессионального интереса с разработки документации на более инженерные задачи, появляется специалист, способный решать сложные технические задачи, отлично ориентирующийся в предметной области и глубоко понимающий потребности коллег.

Постаралась быть краткой и не лить много воды. Буду благодарна, если коллеги из других компаний поделятся своим опытом в комментариях. Мы в YADRO стараемся следить за всеми актуальными тенденциями в области разработки технической документации и мне было бы чрезвычайно интересно узнать, как этот процесс построен у вас.