Как стать автором
Обновить
Цифра
Разрабатываем и внедряем промышленные ИТ-решения

Docs-as-code: DevOps-технологии в документировании, или Как подружить технического писателя и разработчика

Время на прочтение 10 мин
Количество просмотров 8.7K

Привет, Хабр! Меня зовут Роман Блинов, я ведущий технический писатель в «Цифре» — в команде по развитию платформы 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 зашла достаточно далеко в его применении, чтобы оценить все плюсы. Рапортовать о завершении этого пути пока рано, но мы работаем над этим.

Теги:
Хабы:
+5
Комментарии 52
Комментарии Комментарии 52

Публикации

Информация

Сайт
www.zyfra.com
Дата регистрации
Дата основания
Численность
1 001–5 000 человек
Местоположение
Россия