Привет, Хабр! Меня зовут Роман Блинов, я ведущий технический писатель в «Цифре» — в команде по развитию платформы ZIIoT. Этот пост будет о подходе Docs-as-code для документирования разработки ПО. Пишу с прицелом на тех читателей (то есть писателей), кто этот подход пока не пробовал и по факту имеет набор файлов в Confluence, файлы формата .docx и .pdf, на поддержку, обновление и оформление которых тратится порядка 70 % времени (а хотелось бы меньше), и 101 отговорку разработчиков, чтобы не участвовать в документировании.
Сначала расскажу, с какими проблемами сталкиваются писатели до перехода на Docs-as-code, затем опишу подход в общих чертах и в конце упомяну об основной трудности его внедрения по собственному опыту и опыту коллег.
На что жалуетесь? Три боли технического писателя до внедрения Docs-as-code
1. Разработчики слабо вовлечены в процесс документирования
Документирование — неотъемлемая часть разработки программного обеспечения, и этот процесс требует участия не только технического писателя, но и разработчиков. Однако последние об этом периодически забывают или по разным причинам пытаются дистанцироваться от процесса. Такой подход недопустим. Разработчик, а равно и его руководитель, при планировании работ должны закладывать определенный объем времени на консультации с техническим писателем. Отсюда крик души технического писателя: не забывайте о нас! Работа над документами — это время и силы. Если вы хотите, чтобы все было сделано хорошо, будьте готовы посвятить немного своего времени данному процессу. Ну и еще очень поможет, если разработчик ведет свои заметки.
2. Команда документирования слабо информирована о ходе разработки
Когда система документирования встроена по формату Docs As Service, группа документирования оторвана от групп разработки и формирует документацию на основе постановок, поступающих от разработчиков. При этом группа документирования не имеет представления о ходе разработки и тех процессах, которые протекают в ее рамках. Более того, ответственные за документацию практически не владеют информацией о развитии продукта и не могут полностью отвечать за консистентность документации и ее актуальность, так как всегда есть человеческий фактор, когда кто-то кому-то банально забыл сказать, что вышел новый релиз или что-то поменялось в текущем. Документация в этом случае превращается в набор файлов в Confluence и других форматах, например, .docx и .pdf, которые постоянно приходится поддерживать, обновлять и вообще держать в адекватном состоянии.
Такой подход ведет к тому, что около 70 % времени тратится на беготню за разработчиком, оформление и переработку документов. Проще говоря, писатель сидит и раскрашивает файлы в корпоративные цвета и правит шрифты и таблицы. И только 30 % времени уходит на формирование самих документов. Согласитесь, это, мягко говоря, неэффективно, и хотелось бы поменять цифры местами. Да и некоторые вопросы остаются без ответов.
3. Нет версионности
Возможна ли версионность при существующем подходе? Что нам делать, если требуются документы на различные релизы? А как быть, если нам потребовались документы на версию продукта годовой давности (как бы смешно ни звучало, но это случай из практики)? Ответ прост: придется сидеть и искусственно старить документы: выкидывать из них новые фичи, менять картинки. Все опять сведется к нашим 70 % (а то и больше) времени на оформление.
Чем лечить будем
Чтобы избавиться от ненужных стрессов, требуется изменить образ жизни технического писателя, точнее подход к документированию. В качестве панацеи в писательской среде уже давно обсуждается и применяется система организации документирования Docs As Part Of Development Team, когда технические писатели включены в процесс разработки и подготовка документов является его неотъемлемой частью. Документация ведется в формате Docs-as-code, основанном на технологиях DevOps в разработке ПО, когда работа над документацией строится на тех же принципах, что и работа над исходным кодом, и передается заказчику в рамках аналогичных процессов.
Проще говоря, в парадигме Docs-as-code команда документирования встает на те же рельсы, что и разработчики, и применяет в своей работе тот же инструментарий и процессы, но только для разработки документации. Документация «живет» в тех же местах, что и код, и передается заказчику так же, как код.
В чем суть и преимущества этого подхода
В основе подхода лежит переиспользование инфраструктуры разработки ПО для ведения документации.
В качестве базы применяется простой текст, написанный в легкой, человекочитаемой разметке, которая остается читаемой даже в исходном виде, что значительно сближает ее с кодом. В качестве основы для хранения используется система контроля версий Git, а релиз осуществляется посредством CI в необходимом формате.
Особенности:
· Ведение документации в простом текстовом формате.
· Использование инструментария и подходов к разработке исходного кода.
Плюсы: не нужно строить отдельную инфраструктуру (она и так уже есть), легко поднимается, понятна для команды разработки.
Минусы: немного сложнее в использовании, техническим писателям без опыта разработки потребуется время, чтобы привыкнуть к процессу и освоить ряд достаточно жестких правил.
Структура разработки документации
Работа над документацией в рамках подхода Docs-as-code включает следующие элементы, повторяющие аналогичные шаги разработки:
1. Текст кода — Текст документа.
2. Система контроля версий кода — Система контроля версий документа.
3. Merge Request для код-ревью — Merge Request для вычитки документации.
4. CI для сборки кода — CI для сборки документа.
5. Code Style и релизные практики — Руководства по стилю и редакционные политики.
6. Автотесты для сборки — Автотесты для документации.
Рассмотрим каждый элемент по порядку.
Текст кода — Текст документа
В основе подхода Docs-as-code лежит легковесная разметка и простой текст. Нами был выбран язык разметки Markdown, т. к. он наиболее прост в освоении и практичен в применении. Можно сказать, что Markdown является стандартом при разработке подобной документации. Также можно применять ASCIIDoc или reStructured Text, но данные языки обладают достаточно большим набором правил, которые необходимо освоить, а также требуют специфического программного обеспечения.
Markdown не требует долгого и кропотливого изучения. Он достаточно понятен даже на уровне интуиции, и все форматирование текста в нем осуществляется при помощи простейших символов типа пробелов, табуляции и т. п. Язык поддерживает все основные способы форматирования текста, которые требуются для оформления документации: заголовки, абзацы, списки, выделение блоков текста, изображения и т. п. При этом в нем довольно ограниченный набор возможностей форматирования, что значительно снижает вероятность испортить текст и сделать его менее читаемым по сравнению с тем же MS Word, где можно перегрузить текст выделениями, некорректно его отформатировать и выполнить множество иных нежелательных действий, не говоря уже о том, что текст, отформатированный в одном шаблоне, чаще всего превращается в полную кашу в другом.
Важная особенность настройки Markdown — возможность применения шаблонов оформления текста документа, где первоначально задается шаблонный стиль, и все документы автоматически будут выходить именно в таком оформлении. Это способствует более корректной работе над документацией в команде, когда над одним документом трудится несколько человек или требуется единообразное оформление всей документации.
Для работы с текстами доступны все расширенные текстовые редакторы. В нашем случае мы применяем редактор VS Code, так как он хорошо встраивается в наш процесс интеграции и доставки обновлений, но можно использовать и другие — Atom и т. п. Кстати, один из редакторов — Typora — позволяет очень легко и быстро преобразовывать текст из двоичных форматов типа .docx в Markdown. И его использование в комбинации с VS Code помогает сильно ускорить процесс переработки документов из других форматов.
Все это позволяет значительно облегчить работу с документацией и ускорить процесс ее разработки. Кроме того, данные инструменты намного проще в работе по сравнению с файлами MS Word и т. п.
Система контроля версий кода — Система контроля версий документа
Как уже говорилось, в качестве системы хранения и контроля версий применяется Git. Особенность Git — наличие веток, посредством которых можно осуществлять контроль над тем, что было создано, отслеживать и откатывать версии, следить за актуальностью, вести совместную работу над документом и т. п.
Такой подход несколько отличается от совместного редактирования документации с использованием Sharepoint и других ресурсов. С одной стороны, скорость такой совместной работы может немного упасть, так как необходимо создавать свою версию файла, а затем осуществлять процесс слияния. То есть не получится быстро взять и набросать какой-то текст. Зато мы получаем процедуру вычитки документации — в процессе Merge Request мы можем контролировать все изменения, отклонять те, что не соответствуют, и не пускать их в основную ветку. Также мы можем увидеть буквально по каждой строке, кто и когда ее создал и изменил. Таким образом, кроме отслеживания изменений глобально по репозиторию мы можем отслеживать их в отдельных файлах.
Отдельный бонус — это возможность создания нескольких версий одного и того же документа. Без Git при наличии нескольких версий системы придется копировать документацию и управлять ими по отдельности. В Git же мы можем сделать несколько веток помимо основной и сливать только те изменения, которые нам необходимы.
Merge Request для код-ревью — Merge Request для вычитки документации
Как уже говорилось выше, для вычитки и согласования текстов документов используется система Merge Request, принятая в Git. При написании отдельного блока документации можно не сразу сливать текст в основную ветку, а создать запрос и отправить его на проверку редактору и техническому специалисту. И здесь снова необходимо подчеркнуть важность использования легковесного языка разметки, который легко читается в исходнике, когда непосредственно в Git мы можем проверить основные моменты текста, прикрепить комментарии и т. п.
CI для сборки кода — CI для сборки документа
Стоит упомянуть о процедуре сборки документа. После создания готового документа возникает необходимость конвертации документа в какой-либо единый формат, который в дальнейшем может быть передан заказчику, и т. п.
При подходе Docs-as-сode документация хранится непосредственно в репозитории с исходным кодом проекта, читаема, как и все материалы в Git, и передается заинтересованному лицу вместе с исходным кодом проекта. Все материалы при таком подходе соответствуют той версии ПО, которая передается заказчику, и автоматически являются актуальными, что значительно снижает временные затраты на актуализацию документов.
В случае же, когда заказчику по каким-либо причинам требуется документация в отчуждаемом формате — .docx, .pdf и т. д., наш подход позволяет сгенерировать необходимый документ с использованием утилиты под названием Pandoc. Данный инструмент позволяет выполнять конвертацию документов из Markdown и обратно в большинство используемых форматов. На выходе мы можем создать практически любой файл и передать его либо разместить в системе управления документацией, которой пользуется заказчик.
Важный аспект при этом — возможность конвертации документа в определенный корпоративный шаблон, когда мы получаем не просто неоформленный документ, а практически полностью готовый к передаче документ, который требует небольшой доработки, например корректировки таблиц. Но даже при таком состоянии дел работа над отчуждаемой версией документа займет в разы меньше времени, чем копирование и форматирование целиком.
Code style и релизные практики — Руководства по стилю и редакционные политики
Markdown поддерживает настраиваемые шаблоны оформления документации, и в данном случае мы можем настроить практически любое правило — как для оформления документа, так и для его содержания. Для этого требуется достаточно подробно проработанное руководство по стилю оформления документации, которое будет максимально адаптировано для используемого подхода и будет составлено исходя из лучших практик его применения. Мы сейчас как раз дорабатываем такой документ у себя, чтобы он был более приспособлен к использованию в рамках подхода Docs-as-code. Важно также подготовить достаточно удобный глоссарий, содержащий основные терминологические единицы, применяемые в рамках разрабатываемого ПО.
Автотесты для сборки — Автотесты для документации
Необходимо упомянуть и о возможности автотестов документации. Так, наш подход позволяет осуществлять следующие варианты проверки документа:
· линтинг разметки и орфографии;
· валидность ссылок;
· соответствие глоссарию.
Отдельные вопросы локализации документации
Для локализации документов у нас применяется открытое ПО Weblate, которое интегрируется с Git и позволяет выполнять локализацию как обычных текстовых файлов, так и json-файлов и др. Важно, что данное ПО работает по системе «память перевода» и позволяет автоматизировать и ускорить процесс перевода за счет накопления базы готовых сегментов текста, которые потом программными средствами вставляются в текст. Это весьма актуально для технических текстов, где содержится большой объем повторяющихся блоков и наименований.
Ну и не без ложечки дегтя
«Классно!» — скажете вы и будете бесконечно правы. Удобный модный формат с автоматизацией большинства функций обработки текста, быстрый процесс передачи и доставки заказчику, версионность — что может быть лучше?! Мы уже победили. Надо только все корректно оформить.
Не тут-то было. Мы общались с представителями разных компаний, которые уже применяют Docs-as-code или только внедряют его в каждодневную практику, и конечно же, все они сталкивались в процессе внедрения с различными трудностями. Мы не исключение. Если суммировать. то можно прийти к пониманию, что трудность всего одна: для перехода на Docs-as-code нужно дозреть.
Да, все классно: быстро, удобно и легко. Но Docs-as-code — это не просто система документации, это нечто более близкое к философии, которая требует в первую очередь строгой внутренней дисциплины, выстроенных бизнес-процессов и, главное, желания улучшить жизнь самим себе. А для этого требуется, как сейчас модно говорить, выйти из зоны комфорта и встать на путь постоянного развития.
С одной стороны, техническому писателю удобно работать по старой системе: сидишь себе спокойно, правишь рисунки в тексте — и время идет, рабочее, между прочим, и зарплата капает. А тут брось все это, изучи что-то новое, да еще освободи 70 % своего рабочего времени. И чем потом это время занимать? Конечно, работой над качеством документации, а это сложнее. С другой стороны, есть разработчик, он всегда занят, у него тысяча задач. Когда ему заниматься рисованием схем и объяснением писателю, а что же, собственно, его сервис делает и как. Конечно, времени нет. А еще есть руководитель проекта, которому в рамках нового подхода придется придумывать, как и когда встроить документирование в процесс работы.
Кроме того, у многих компаний, растущих методом слияний и поглощений, есть наследство из практиков старой закалки, которым требуется время на адаптацию к новой корпоративной культуре и которые не всегда легко принимают новые правила.
Создание и развитие хорошего продукта всегда идет параллельно с развитием команды, его создающей, а это включает также улучшение процессов разработки и документирования. Подход Docs-as-code этому способствует, и наша команда разработки ZIIoT зашла достаточно далеко в его применении, чтобы оценить все плюсы. Рапортовать о завершении этого пути пока рано, но мы работаем над этим.