Качественная документация — один из столпов успешного IT-продукта, но её создание часто остается в тени разработки. В Postgres Professional этот процесс выстроен не менее строго, чем написание кода. Удивительно, но всем этим огромным хозяйством управляет команда из десяти человек. Мы попросили старшего технического писателя Екатерину Гололобову провести для нас экскурсию по её «цеху»: от постановки задачи до финального коммита.
Кто и на чём пишет документацию в Postgres Pro
Вопреки распространённому мнению, документацию для всех продуктов Postgres Pro пишут не разработчики, а команда технических писателей, которая за последний год выросла вдвое. Поскольку Postgres Pro — это форк PostgreSQL, исходную документацию мы разрабатываем на английском, а затем переводим её на русский язык.
Чем пользуемся:
DocBook XML — основной язык разметки документации, который мы наследуем от ванильного PostgreSQL. DocBook XML позволяет собирать документацию в разных форматах: HTML для сайта, PDF и EPUB для офлайн-доступа клиентов.
Markdown — язык документации DBaaS-продуктов.
Weblate — инструмент для локализации, который помогает переводить и документацию, и сообщения Postgres Pro (да-да, тексты ошибок и предупреждений, которые вы видите в консоли), а ещё документацию ванильного PostgreSQL.
Pandoc — конверует документацию из Markdown, reStructudredText и других форматов в DocBook XML.
Figma — инструмент для разработки интерфейсов, в котором мы вычитываем UX-тексты продуктов Postgres Pro с графическим пользовательским интерфейсом (DBaaS, PPEM).
Воркфлоу документации — почти квест
Наш рабочий процесс — это многоступенчатый и сложный квест.
Постановка задачи. В процессе постановки задачи на новую фичу разработчик может запросить для этой фичи документацию. В этом случае автоматически создаётся задача на документацию, которая «падает» тимлиду, а он направляет её одному из коллег-техписателей.
Подготовка черновика. Техписатель погружается в тему: изучает задачу, переписку разработчиков, внутреннюю документацию и даже смотрит код, чтобы досконально понять суть фичи. Если тема сложная, мы просим разработчика провести демо.
SME review (фактчек). Готовый черновик отправляется на вычитку разработчику. Часто этап превращается в цикл: мы вносим правки, отправляем их на вычитку, получаем новые комментарии — и это продолжается до тех пор, пока эксперт не будет доволен результатом.
Peer review (проверка техписателем). После апрува разработчика документ уходит на вычитку другому техническому писателю. Здесь проверяется всё: от грамматики английского языка до соответствия глоссарию и стайлгайду.
Коммит и перевод. Только после двух кругов ревью и утверждений английская версия считается готовой, и мы коммитим её в ту же ветку, где велась разработка. После этого начинается магия: специальный скрипт автоматически забирает новые тексты и отправляет их в Weblate на перевод.
Проверка перевода и релиз. Переведённый на русский язык текст снова проходит peer review, где проверяется качество перевода и корректность терминологии. После финальных правок мы ждём релиза.
Как мы работаем с документацией PostgreSQL
Помимо документации к своим продуктам, мы полностью переводим документацию к релизам ванильного PostgreSQL. И это не просто перевод: мы готовим патчи для самой ваниллы, если находим в документации неточности или ошибки.
Процесс здесь тоже автоматизирован. Скрипт забирает оригинальные sgml-файлы из репозитория PostgreSQL, с помощью утилиты xml2po преобразует их в формат .po (Portable Objects), который и загружается в Weblate. После того как мы завершаем перевод, файлы тем же путем возвращаются в наш репозиторий, откуда их забирает релизная группа.
Обратная связь
Мы активно собираем обратную связь из самых разных источников:
Внутренний чат: наши же сотрудники (особенно из техподдержки и консалтинга) — одни из самых активных пользователей документации, они первыми сообщают об ошибках или нехватке информации.
Форма на сайте, через которую любой пользователь может сообщить о проблеме.
Личные сообщения по почте и в мессенджерах.
Мы стараемся обрабатывать абсолютно все запросы, но вносим правки не сразу, так как наш релизный цикл тесно связан с разработкой. Тем не менее будьте уверены: ни одно сообщение не потеряется и будет учтено в ближайшем релизе.