Привет, я — Таня Кириллова, технический писатель команды развития безопасности контейнеров в Cloud.ru.
На конференции Techwriters Days 2 Семён Факторович, основатель и руководитель компании documentat.io, в своем докладе Техписатель-2025 предложил ввести специализации для профессии «Технический писатель». В качестве одной из таких он выделил направление Cloud-техписатель.
Чем Cloud-техписатель отличается от обычного технического писателя? Тем, что извлекает информацию из голов разработчиков и самих сервисов, адаптирует собранную информацию для пользователей, разрабатывает практические сценарии совместно с девопсами, работает с документацией, как с кодом, документирует API, пишет Release Notes… и все это для облачных сервисов.
В статье расскажу, с какими вызовами сталкивается наша команда Cloud-техписателей при разработке документации для облачных сервисов, и поделюсь опытом их преодоления.
Особенности документирования облачных сервисов
С какими трудностями мы встречаемся при разработке документации для наших облачных сервисов?
Сложность сервисов. Облачная инфраструктура Cloud.ru состоит из более 100 сервисов. Наши технические писатели чаще всего работают с документаций нескольких сервисов одновременно. Каждый сервис — самостоятельный сложный IT-продукт, предназначенный для специалистов с определенной технической экспертизой. Чтобы создавать документацию, соответствующую потребностям и уровню знаний целевой аудитории, нашим техническим писателям приходится хотя бы базово учиться работать со своими сервисами, а это не так просто.
Обработка большого объема информации. Техническим писателям приходится обрабатывать огромный объем информации, которая поступает от экспертов. Ведется интенсивная разработка сервисов, а это значит нам также быстро нужно описать множество функций, настроек, концепций, разработать интересные и полезные сценарии работы с сервисом. Эту документацию важно разместить в общей документации так, чтобы пользователи могли быстро все находить.
Перевод сложных концепций на понятный язык. Одна из задач технического писателя в облачных сервисах — объяснять сложную техническую информацию простым языком, не теряя важные детали, чтобы с сервисом по этой доке могли быстро разобраться как новички, так и профи.
Актуальность документации. С учетом активной разработки сервисов и частого обновления облачным техническим писателям необходимо следить за актуальностью документации, а это требует оперативного реагирования на изменения и своевременного внесения корректировок. Это становится еще более сложной задачей без эффективных методов отслеживания обновлений.
Преодолевая эти трудности снова и снова, мы чувствовали себя так, как будто каждый раз боремся с драконом, который никак не хочет покориться. Пришлось найти способы справляться с этими трудностями, и постепенно мы выстроили процесс, который позволил нам приручить его.
Наш путь разработки документации
Для нас работа над документацией в облачном сервисе — это как прогулка по извилистой дороге, полностью пройдя которую в итоге удается «приручить дракона».
На этом пути есть три основные остановки:
Собираем все возможные данные о том, что нужно задокументировать.
Разрабатываем план и пишем сам документ.
Смотрим на все свежим взглядом и выпускаем в свет.
Посмотрим на каждый этап более подробно.
Собираем информацию: вызовы и решения
Пожалуй, один из самых сложных этапов в разработке документации — это сбор информации. Есть два основных подхода:
Поработать с фичей, исследовать ее и на основе полученного опыта задокументировать результат.
Использовать коммуникации, то есть задавать вопросы, получать ответы и на основе полученной информации разрабатывать документацию.
Однако каждый из вариантов имеет свои трудности.
Мы столкнулись с тем, что техническому писателю самостоятельно разобраться с работой какой-то фичи в наших сервисах трудно. Например, без опыта трудно воссоздать, как пользователи работают с продуктом. А эксперты, которые знают продукт досконально, не всегда могут уделить внимание общению.
Чтобы справиться с этими двумя проблемами, мы пустили в ход несколько приемов.
Изучаем теорию
Знание теории помогает нашим техническим писателям задавать более направленные вопросы экспертам: это экономит время экспертов и улучшает качество собранных данных.
Но в каком объеме техническому писателю изучать теорию? И нужно ли знать все досконально?
Например, Сара Меддокс, технический писатель из Google, в разных постах своего блога делится, как техническому писателю изучать в том числе и облачные сервисы.
Вот примерный алгоритм:
Получить общее представление о сервисе: изучить основные термины и базовые концепции.
Сформулировать вопросы в процессе изучения.
Изучить существующую документацию или аналогичные решения и их документацию.
Попробовать выполнить самые простые сценарии на тестовых стендах.
Встретиться с экспертами и задать сформулированные вопросы.
Поделиться своими знаниями, например, с коллегами, чтобы закрепить понимание.
Мы взяли этот алгоритм на вооружение и, чтобы погрузиться в новый сервис, начиная разработку документации для него, обязательно следуем ему.
Проводим собственное расследование перед интервью с экспертом
Чтобы понимать немного о фиче, работу с которой нужно задокументировать, перед встречей с экспертом мы:
-
Изучаем артефакты, которые есть во внутренней базе знаний:
Use Cases от аналитиков.
Architecture Decision Records (ADR) от архитекторов.
Request For Comments (RFC) от разработчиков.
Пробуем самостоятельно поработать с фичей. Если не получается — ничего страшного — на встрече попросим эксперта показать, чтобы потом самостоятельно повторить.
Обязательно продумываем вопросы к эксперту.
Организуем встречу так, чтобы у эксперта было достаточно времени ответить на все наши вопросы. Например, помним, что в начале спринта нагрузки у эксперта меньше.
Эти шаги помогают нам уверенней себя чувствовать на встречах с экспертом, формулировать более направленные вопросы и понимать, что происходит, когда эксперт показывает работу с фичей.
Самостоятельно экспериментируем
Для этого освоили работу с некоторыми инструментами:
Изучили, как работать с API в Postman и с помощью curl.
В наших сервисах новые возможности в API появляются быстрее, чем в личном кабинете. Поэтому, умея выполнить API-запрос, мы можем получить информацию о том, как фича работает, гораздо раньше. Это помогает нам поэкспериментировать, а затем написать хороший текст в будущий UI.Освоили работу в консоли разработчика в браузере. Это помогает нам, например, «примерять» тексты в UI.
Научились работать с командной строкой и освоили работу работу с инструментами своих сервисов. Например, для Evolution Managed Kubernetes — это kubectl, cloudlogin, k9s.
Умение работать с этими инструментами помогает нам «щупать» фичи без помощи экспертов или хотя бы понимать, что выполняет эксперт, когда показывает работу какой-то фичи.
Разрабатываем контент: проблемы и решения
В чем заключаются основные сложности на этом этапе? Создание хорошей документации для облачных сервисов требует обработки большого объема информации.
Конечно, важно грамотно структурировать и расположить контент, чтобы пользователь мог быстро найти нужную информацию. Также важно поддержать консистентность всей документации. И еще документация должна выходить вместе с фичей, запаздывание часто критично — пользователю будет сложно разобраться с новой функциональной возможностью без нее.
Типизация информации
Справиться с объемом и поддержать консистентность нам помогла типизация информации. Этот подход основан на методиках DITA и Diátaxis. Контент делится на четко определенные категории: концепции, инструкции, справочники и сценарии.
В основе документации Cloud.ru заложены принципы типизации. Мы также адаптировали типизацию под особенности своих сервисов. Например, добавили тип топиков «Решение проблем».
Что дает нам типизация информации? Контент единообразно структурирован и документация консистентна: технический писатель понимает куда разместить контент. А пользователи понимают принцип структурирования информации в нашей документации от сервиса к сервису и знают, куда идти, например, если им нужна какая-то инструкция.
Шаблоны
Чтобы ускорить разработку документации, используем шаблоны. Как для структуры всего документа, так и для определенных типов документов.
Шаблон по сути это готовая структура будущего документа, которую нам остается наполнить. Используя шаблон, мы можем быстрее сформулировать и конкретизировать вопросы для себя и для источника знаний.
Шаблоны можно разработать самим, а можно пользоваться готовыми. Есть целые библиотеки таких шаблонов.
Генерируем документацию из кода
Чтобы ускорить разработку и публикацию документации, используем генерацию из кода. Например, для Evolution Managed Kubernetes из кода мы генерируем спецификацию для API и справочника Terraform.
В документации Cloud.ru для представления справочника API мы используем инструмент Redoc. Redoc позволяет генерировать документацию на основе спецификации в формате OpenAPI. То есть достаточно одного правильно оформленного json- или yaml-файла, чтобы быстро опубликовать справочник в документации. Такой справочник легко поддерживать, заменяя спецификацию на актуальную в репозитории с документацией.
Однако подготовка спецификации достаточно трудоемкий процесс, требующий серьезных временных затрат. Приведу пример: сейчас спецификация для справочника API сервиса Evolution Managed Kubernetes содержит более 3 000 строк, а спецификация для справочника API сервиса «Виртуальные машины» — более 14 000 строк. Собирать вручную такой справочник — дорого.
Поэтому мы на берегу договорились с командой генерировать спецификацию из кода. Наши разработчики описывают структуру данных будущего API и комментарии к сущностям в proto-файлах. Далее запускают генерацию спецификации. Задача технического писателя доработать комментарии разработчика к методам и свойствам в соответствии с нашим стайлгайдом, чтобы обеспечить понятность и доступность информации для конечных пользователей. Важно, что все комментарии правятся в proto-файлах. Иначе, если править саму спецификацию, то при последующих обновлениях все предыдущие изменения текста будут затерты.
Процесс в команде Evolution Managed Kubernetes обычно выглядит следующим образом:
Разработчик создает в системе контроля версий Merge Request (MR) с новыми proto-файлами и сгенерированной спецификацией.
Технический писатель просматривает эти изменения и вносит необходимые правки в комментарии к коду.
После внесения изменений спецификация снова генерируется.
Финальный этап — это интеграция с порталом документации и последующая публикация обновленной версии справочника.
Что касается документации для Terraform, в Evolution Managed Kubernetes процесс несколько отличается. Документация хранится вместе с провайдером Terraform на GitHub. Совместно с разработчиком мы подготовили шаблон документа для каждого ресурса Evolution Managed Kubernetes.
В рамках этого шаблона мы используем инклюды, чтобы добавить на страницу примеры ресурсов, такие как базовый, простой и расширенный, а также описание параметров для этих примеров. Эти параметры автоматически генерируются из комментариев, оставленных в схеме ресурса.
Разработчик формулирует комментарии по своему усмотрению, после чего создается Merge Request (MR). Технический писатель автоматически подключается к MR для проверки текстов. После внесения правок документация снова генерируется. Технический писатель утверждает MR в части, касающейся документации.
Затем разработчик публикует провайдер на GitHub вместе с обновленной документацией, созданной по шаблону, с новыми примерами и описаниями параметров. Этот процесс позволяет документации выходить одновременно с внедрением новой функции.
Публикуем документацию
Следующий важный этап — это публикация документации.
Основная проблема при публикации документации — это фактическое ревью текста. Часто бывает, что эксперты, которые должны проверять документацию, перегружены задачами и не могут уделить этому достаточно времени. Это может привести к пропуску ошибок.
Чтобы решить проблему, мы, по возможности, проводим самопроверку — выполняем сценарии по написанной документации. Внимание эксперта акцентируем только на спорных или неясных моментах.
Однако, тут могут возникать разногласия: например, один эксперт может настаивать на детальном описании алгоритмов, тогда как другой может иметь свои представления о соблюдении стайлгайдов или акцентах в тексте. В таких случаях мы договариваемся и ищем компромиссы, привлекая при необходимости других экспертов, но делая это тактично.
Многочисленные правки тоже могут утомлять обе стороны — как эксперта, так и технического писателя. Если количество итераций правок превышает три, то стараемся обговорить их голосом, чтобы избежать недопонимания.
Обновляем документацию: автоматизация
В облачные сервисы вовлечено большое количество разработчиков и, если не настроить процесс, очень сложно следить за обновлениями.
Как мы подошли к этому вопросу:
Настроили в системе управления задачами автоматическое создание задачи на обновление документации.
Посещаем регулярные встречи команды. Они помогают нам быть в курсе всех изменений, которые происходят в продукте, и позволяют оперативно вносить необходимые правки и получать обратную связь от разработчиков.
Выполняем регулярный аудит документации — сверяем документацию с текущим состоянием интерфейсов и функциональных возможностей, выявляя и исправляя устаревшую или неточную информацию.
Вместо заключения
Итак, подведем итоги. Чтобы упростить свою жизнь облачных технический писателей, мы:
Активно обучаемся. Сосредоточились на изучении теории и освоении инструментов работы с сервисами.
Экспериментируем. Используем инструменты сервиса для самостоятельных проб.
Используем типизацию контента и шаблоны. Поддерживаем единый стиль и логичную организацию документации.
Используем генерацию документации. Генерируем справочники API и Terraform из кода. Это позволяет нам быстрее адаптировать изменения и поддерживать актуальность информации.
Вовремя получаем сведения об обновлениях. Настроили систему управления задачами для автоматического создания задач на обновление документации. Регулярно участвуем в командных встречах и проводим аудит текущего состояния документации.
Минимизируем фактические ошибки. Проверяем инструкции, пробуя пошагово выполнить их, делаем акцент на сложных и сомнительных местах во время проверки документации экспертом.
Эти шаги помогают нам справляться с вызовами при создании и поддержании документации для облачных сервисов, превращая этот процесс в увлекательное и полезное путешествие по «приручению собственного дракона».
А как вы справляетесь трудностями разработки документации в своих продуктах? Буду рада почитать в комментариях.
