Привет, Хабр! Меня зовут Вячеслав Смирнов, я руковожу техническими писателями в Platform V Pangolin. Три года назад я пришел в продукт в качестве DBA, а спустя год организовал команду техписов и стал разрабатывать документацию.

Давным-давно команда Pangolin состояла из 15-20 человек. Документация по продукту была в зачаточном состоянии. Разработчики сами пилили фичи и сами же их описывали. Но потом Pangolin вырос, вышел на внешний рынок и нам стали нужны профессиональные технические писатели.

А мир техписов разнообразен: здесь есть и редакторы-корректоры, и технари, умеющие развернуть дистрибутив. Техписы без технического опыта не всегда готовы разбираться в сложном продукте. Но, как выяснилось на практике, и технарям, пришедшим в команду, не хватало погружения в тему СУБД, чтобы писать документацию. Попробовав разные варианты, мы нашли для себя такой выход: наши техписы обязательно проходят базовые курсы DBA, и мы берем в команду не только техписов, но и DBA, желающих писать доку.

Расскажу, почему я считаю, что техпису обязательно погружаться в продукт настолько глубоко. Буду рад вашим мнениям.

Задачи техписов. С чем мы сейчас имеем дело?

Легаси

В то время, пока у Pangolin не было организованной технической документации, он успел обрасти артефактами и инструкциями, не всегда написанными понятно для пользователя. А продукту, у которого уже больше 80 тыс. инсталляций, нужна исчерпывающе понятная документация. Значит, весь этот материал нужно отрефакторить, структурировать, завязать между собой перекрестными ссылками и переписать нормальным техническим языком.

Релиз никто не отменял

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

Это разработчики между собой могут говорить «сквозная двухфакторная аутентификация». Но техпис, разобравшийся в предмете, сразу представит, что сквозная аутентификация реализована на pgbouncer, а двухфакторная – на СУБД, а это два разных компонента. Поэтому в документации он напишет правильно: «Двухфакторная аутентификация с включенной сквозной аутентификацией на pgbouncer».

Или же они могут говорить: «По умолчанию механизмами двухфакторной аутентификации являются 2f-scram-sha-256 и 2f-ldap». Техпис, который правильно понял разработчика, должен представлять, что механизм двухфакторной аутентификации служит объединением двух методов аутентификации cert+password. А в доке ему надо написать: «По умолчанию в Platform V Pangolin включены методы аутентификации 2f-scram-sha-256 и 2f-ldap. При необходимости использовать методы аутентификации 2f-md5 и 2f-password, нужно добавить их в параметр enabled_extra_auth_methods в конфигурационном файле Pangolin».

Бэклог длиною в жизнь

Обработку багов, техдолг и backlog тоже никто не отменял. Если техдолг и backlog могут чуть подождать, то у багов есть SLA.

Помимо этих направлений, нужно заниматься развитием продукта. Интегрировать ванильную документацию по PostgreSQL в Pangolin, разрабатывать курсы, готовить материалы для маркетинга и многое другое.

Разработка в фича-командах

В нашем продукте мы разрабатываем функциональности, которые преимущественно отличают Platform V Pangolin от ванильного PostgreSQL.

Разработка проходит в фича-командах. В команду входит разработчик (core), тестировщик (QA), технический писатель (TW) и фича-лид, который координирует действия команды.

Обязательные артефакты к разработке — документы: Бизнес требование (БТ), Функциональное решение (ФР) и Критерии приёмки (КП).

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

Что значит участвовать в разработке?

Обращать внимание коллег в фича-команде на то, достаточно ли в документации данных для пользователя. Так, например, при разработке/доработке фичи необходимо:

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

• описать фичу через призму Установка-Настройка-Сопровождение

• если фича затрагивает несколько компонентов продукта, то описать их точки конфигурирования

• проследить за тем, как фича влияет на другие функциональности в продукте и описать это взаимовлияние в документации

• на этапе тестирования фичи необходимо выявить и описать ее возможные ограничения, особенности.

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

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

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

Техпис дополняет раздел «Часто встречающиеся проблемы» фактами и рекомендациями. Информацию берет у команды поддержки в базе знаний. Помимо этого, техпису необходимо актуализировать описание продукта в соответствующих разделах, а также добавить разрабатываемую фичу в перечень функциональных возможностей нового релиза. Описание лицензионного соглашения тоже ложится на его плечи, ведь клиенту важно понимать, под какой лицензией продукта доступна новая функциональность.

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

Что значит следить за целостностью артефактов?

В идеальном мире разработка фичи начинается после согласования БТ, ФР, КП. Но в реальной жизни она начинается тогда, когда начинается, а параллельно с этим идет разработка документов БТ, ФР, КП. Имеет смысл не отпускать эту параллельную активность на самотек. Почему? Да очень просто!

Техпис черпает творческое озарение из материалов, которые предоставляет ему фича-команда в виде обязательных артефактов. Именно оттуда он собирает информацию, структурирует и несет потом в маркдаун.

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

В последнюю неделю до сдачи релиза на техписа выливается ушат материала со всех фичей от разработчиков. Тут остается только прыгать — думать некогда — никакого творчества. Копипаст спасет доку!

В своем классическом состоянии техпис — это вечный ждун материалов. Ему все должны что-то предоставить. Хотя техническому писателю крайне важно получить материал для доки как можно раньше, чтобы размазать работы по всем фичам во времени и отнести в маркдаун материал в соответствии со структурой изложения, а не просто плюхнуть в плошку кашу из поварешки.

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

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

Правильные техписы в продуктовой команде

«Подиум» — это журнал мод, поэтому интерес к моде здесь играет ключевую роль.

© Дьявол носит Prada.

Техпису в IT можно не быть айтишником, но понимать профессиональные термины и сленг — обязательное условие.

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

При работе с  СУБД техпису важно понимать:

  - что такое база данных,
  - какие используются объекты СУБД,
  - что такое репликация,
  - различия между конфигурацией сервера: standalone, cluster,
  - понятия high availability, disaster recovery,
  - что такое блокировки, уровни изоляции, групповые роли, наследование прав.

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

В детстве мы спорили: кто победит каратист с черным поясом или мастер спорта по боксу. Сегодня те же споры, только участники другие. Взять сильного техписа и сильного DBA. Кто лучше напишет доку по СУБД?  Мнение, основанное на опыте, — никто.

Давайте разбираться.

Задача: Описать в документации команды резервного копирования конфигурационных файлов СУБД средствами операционной системы.

Для DBA тут и описывать нечего — и так понятно.
Для техписа тоже проблем нет: «Давайте материал, опишу!»

Вероятно, получится так: разработчик напишет сленговым языком список команд, а техпис, не поняв в этом ничего, зальет в продукт. Оптимизируем процесс. Исключим одного из участников.

Исключаем техписа. Разработчик описывает процесс резервного копирования, сам переводит текст в маркдаун и пулреквестит в репу. Взглянем правде в глаза, много ли таких разработчиков, которые любят и умеют писать документацию? Язык, на котором они разговаривают, не каждому понятен, а уж читать документацию на этом языке порой уж просто невозможно. Оно и понятно — предназначение и целеполагание у них иное. Разработчики мыслят другими категориями, они находятся в контексте проблемы. Для разработки документации нужны другие скилы.

Исключаем разработчика. Много вы видели техписов, которые знают, какие и для чего существуют конфиги СУБД? Какие средства резервного копирования существуют в операционных системах? И тут то же самое. Необходимо погрузиться в контекст, но описывать задачу, будучи извне. Надо как бы надеть майку пользователя и описать последовательность действий понятными ему словами.

Эксперимент Pangolin: как наши DBA писали доку

Инженерам из L3, DBA, 15+ лет опыта, поручили разработать разделы документации по отдельным функциональностям продукта. Требования к стилистическому изложению, структуре и оформлению понизили до нуля. Главное, чтобы разделы были технически грамотные.

Из 12 человек справилось только двое. Для большинства сотрудников это стало пыткой. В результате работа была сделана на «отвяжись» в самой грубой формулировке этого термина.

Дело в том, что мыслить конечным результатом продуктовой команды могут, наверное, только в «бирюзовых» компаниях, когда команда достигла высшей степени зрелости. Когда каждый сотрудник отвечает не только за свои задачи, а еще и за то, как результат его деятельности влияет на продукт в целом. Это в будущем, а пока надо формально заполнить БТ, ФР, КП и быстрее погрузиться в разработку. Ведь если неправильно читать манифест аджайла, то главное — продукт, который работает, а доку все равно никто не читает :). Техпис берет этот сырой и зачастую неполный материал, в котором он разбирается лишь интуитивно, и несет его в маркдаун.

Кто отвечает за качество доки, которая получилась при таком подходе? Техпис, который надеется на разработчика, или разработчик, который отвечает за работоспособность фичи, но никак не за доку?

Впрочем, два человека из двенадцати — тоже результат. В нашей ситуации это вселяло надежду — DBA могут научиться писать доку при желании. Команде здорово подошли бы люди, которые админили в прошлом Oracle или MSSQL. С таким бэкграундом легко описывать процессы внутри PostgreSQL.

Так мы оказались перед выбором: искать админов и делать из них техписов или найти техписов и учить админить? И тех, и других на рынке почти нет. Но все же классических технических писателей больше, чем администраторов БД, желающих писать документацию. Волшебной таблетки не нашли, а значит ищем специалистов из обеих категорий. Техписов научим админить, а админов научим писать.

Мотивация к трансформации

Вопрос, надо ли техпису погружаться в предмет администрирования СУБД именно на уровне DBA, — непростой. Профессия технического писателя востребована в разных областях народного хозяйства. Сегодня работаешь айтишником, завтра — в конструкторском бюро, послезавтра — документируешь механизмы и машины для нефтедобывающей отрасли. Зачем тратить время на изучение СУБД, если потом может возникнуть желание описывать атомные реакторы или медицинское оборудование? Каждый для себя решает сам.
 
Мы решили, что Pangolin — сложный продукт и знания в области СУБД для технического писателя — элементарная гигиена. В тот момент у нас уже было два технических писателя (надеюсь, скоро станет больше). Они сами про себя рассказали:

Станислав: По образованию типичный айтишник, по призванию технический писатель. До того, как стал техническим писателем, отработал несколько лет в QA. Любит докапываться до самых мелочей, которые другие не замечают. В техписательстве уже пять лет, три года из которых писал доки только на английском. Главный старожил команды документирования Pangolin.

Светлана: Закончила университет по направлению «Информатика и вычислительная техника». За время учебы в университете поработала и как специалист по качеству оборудования, и как фулстэк-разработчик. После университета ушла в анализ данных и занималась этим два года, а затем перешла в технические писатели.

Так вот, однажды мне нужно было прийти и сказать им, что мир изменился, текущих компетенций не хватает. Надо прокачаться до уровня сложности нашего продукта. Уметь устанавливать стенды, тестировать фичи и параллельно изучать базовые операции администрирования PostgreSQL…

Справедливости ради, наши технические писатели легко приняли изменения внешнего мира и трансформацию профессии. Стали изучать DBA-1,2,3, разворачивать стенды, разбираться с конфигами, параметрами, процессами.

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

Нашим техписам нелегко. Материал сложный, погружение в детали занимает время. Вдобавок они постоянно посещают митапы, фичевые демо. Если этого не делать, не пропускать материал через мозг, можно скатиться в парадигму копипаста и понизить качество документации. Это недопустимо.

Траектория развития техписов в нашей команде лежит через изучение курсов DBA. Сегодня это доступные курсы в сети, но мы начали разрабатывать наши курсы по Platform V Pangolin и будем переводить новых технических писателей на свои программы. Помимо этого, мы планируем свою программу сертификации по Pangolin.

Вместо заключения

Техпис — интереснейшая роль в команде. Разрабатывая доку, он сталкивается со всеми сторонами продукта. Не каждый разработчик знает о продукте так много.

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

Понимаю, что наш подход — не единственно возможный, и с удовольствием почитаю в комментариях ваши мнения.

Олды, бывшие и нынешние DBA, которых судьба, возможно, оставила без работы в связи с уходом с рынка известных вендоров СУБД! Вы можете попробовать себя в новом качестве, ведь ваш бэкграунд, многолетний опыт администрирования и работы с документацией как никогда востребован именно сейчас. Переход в технические писатели — хороший вариант для тех, кто устал от саппорта и админки и, конечно, для тех, кто любит делиться знаниями. Буду рад вашим откликам на вакансию техписа здесь и здесь. 

А еще мы регулярно рассказываем о жизни отдела технических писателей в сообществе нашей команды, присоединяйтесь!

PS: Благодарочка Светлане Сагадеевой за редактуру, критику и ценные замечания.