Docs as code что такое
Как пишут документы. Docs as code. Часть 1
Я уже рассказал про Confluence и Microsoft Word, с которыми работал на предыдущих местах. Теперь хочу рассказать про методику Docs as code, которую использую сейчас.
Немного об этом
Docs as code — это разработка документации с помощью тех инструментов, которые используют программисты:
Я думаю, что эта методика разработки документов самая сложная в начале и при этом самая интересная. Здесь я расскажу о преимуществах Docs as code.
Возможность выбора. Можно выбрать текстовый редактор:
Я работаю с Microsoft Visual Studio Code. Он легковесный, удобный и настраиваемый. Он позволяет работать с несколькими файлами одновременно. В маркетплейсе есть много полезных плагинов под разные нужды.
Можно выбрать формат для исходных текстов:
Можно выбрать место для хранения документов.
Типы документов. Исходные тексты можно сохранять в форматы:
Для сборки документов из markdown мы используем Foliant.
Коллективная работа. Все инструменты рассчитаны на коллективную работу. С помощью Git удобно читать документы, делать комментарии, хранить разные версии одного документа.
Технологии разработчиков. Методика Docs as code обязывает технического писателя работать с инструментами программиста. Это позволяет легко документировать такие вещи, как программный код или таблицы в базе данных. А затем быстро вернуться к написанию текста.
Как видите, у Docs as code есть много преимуществ. После работы в Microsoft Word появляется ощущение свободы 🙂 Но у методики есть и недостатки. О них я расскажу в следующий раз.
Docs-as-code: DevOps-технологии в документировании, или Как подружить технического писателя и разработчика
Сначала расскажу, с какими проблемами сталкиваются писатели до перехода на Docs-as-code, затем опишу подход в общих чертах и в конце упомяну об основной трудности его внедрения по собственному опыту и опыту коллег.
На что жалуетесь? Три боли технического писателя до внедрения Docs-as-code
1. Разработчики слабо вовлечены в процесс документирования
Документирование — неотъемлемая часть разработки программного обеспечения, и этот процесс требует участия не только технического писателя, но и разработчиков. Однако последние об этом периодически забывают или по разным причинам пытаются дистанцироваться от процесса. Такой подход недопустим. Разработчик, а равно и его руководитель, при планировании работ должны закладывать определенный объем времени на консультации с техническим писателем. Отсюда крик души технического писателя: не забывайте о нас! Работа над документами — это время и силы. Если вы хотите, чтобы все было сделано хорошо, будьте готовы посвятить немного своего времени данному процессу. Ну и еще очень поможет, если разработчик ведет свои заметки.
2. Команда документирования слабо информирована о ходе разработки
Такой подход ведет к тому, что около 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 — возможность применения шаблонов оформления текста документа, где первоначально задается шаблонный стиль, и все документы автоматически будут выходить именно в таком оформлении. Это способствует более корректной работе над документацией в команде, когда над одним документом трудится несколько человек или требуется единообразное оформление всей документации.
Все это позволяет значительно облегчить работу с документацией и ускорить процесс ее разработки. Кроме того, данные инструменты намного проще в работе по сравнению с файлами MS Word и т. п.
Система контроля версий кода — Система контроля версий документа
Как уже говорилось, в качестве системы хранения и контроля версий применяется Git. Особенность Git — наличие веток, посредством которых можно осуществлять контроль над тем, что было создано, отслеживать и откатывать версии, следить за актуальностью, вести совместную работу над документом и т. п.
Такой подход несколько отличается от совместного редактирования документации с использованием Sharepoint и других ресурсов. С одной стороны, скорость такой совместной работы может немного упасть, так как необходимо создавать свою версию файла, а затем осуществлять процесс слияния. То есть не получится быстро взять и набросать какой-то текст. Зато мы получаем процедуру вычитки документации — в процессе Merge Request мы можем контролировать все изменения, отклонять те, что не соответствуют, и не пускать их в основную ветку. Также мы можем увидеть буквально по каждой строке, кто и когда ее создал и изменил. Таким образом, кроме отслеживания изменений глобально по репозиторию мы можем отслеживать их в отдельных файлах.
Отдельный бонус — это возможность создания нескольких версий одного и того же документа. Без Git при наличии нескольких версий системы придется копировать документацию и управлять ими по отдельности. В Git же мы можем сделать несколько веток помимо основной и сливать только те изменения, которые нам необходимы.
Merge Request для код-ревью — Merge Request для вычитки документации
Как уже говорилось выше, для вычитки и согласования текстов документов используется система Merge Request, принятая в Git. При написании отдельного блока документации можно не сразу сливать текст в основную ветку, а создать запрос и отправить его на проверку редактору и техническому специалисту. И здесь снова необходимо подчеркнуть важность использования легковесного языка разметки, который легко читается в исходнике, когда непосредственно в Git мы можем проверить основные моменты текста, прикрепить комментарии и т. п.
CI для сборки кода — CI для сборки документа
Стоит упомянуть о процедуре сборки документа. После создания готового документа возникает необходимость конвертации документа в какой-либо единый формат, который в дальнейшем может быть передан заказчику, и т. п.
При подходе Docs-as-сode документация хранится непосредственно в репозитории с исходным кодом проекта, читаема, как и все материалы в Git, и передается заинтересованному лицу вместе с исходным кодом проекта. Все материалы при таком подходе соответствуют той версии ПО, которая передается заказчику, и автоматически являются актуальными, что значительно снижает временные затраты на актуализацию документов.
Важный аспект при этом — возможность конвертации документа в определенный корпоративный шаблон, когда мы получаем не просто неоформленный документ, а практически полностью готовый к передаче документ, который требует небольшой доработки, например корректировки таблиц. Но даже при таком состоянии дел работа над отчуждаемой версией документа займет в разы меньше времени, чем копирование и форматирование целиком.
Code style и релизные практики — Руководства по стилю и редакционные политики
Markdown поддерживает настраиваемые шаблоны оформления документации, и в данном случае мы можем настроить практически любое правило — как для оформления документа, так и для его содержания. Для этого требуется достаточно подробно проработанное руководство по стилю оформления документации, которое будет максимально адаптировано для используемого подхода и будет составлено исходя из лучших практик его применения. Мы сейчас как раз дорабатываем такой документ у себя, чтобы он был более приспособлен к использованию в рамках подхода Docs-as-code. Важно также подготовить достаточно удобный глоссарий, содержащий основные терминологические единицы, применяемые в рамках разрабатываемого ПО.
Автотесты для сборки — Автотесты для документации
Необходимо упомянуть и о возможности автотестов документации. Так, наш подход позволяет осуществлять следующие варианты проверки документа:
· линтинг разметки и орфографии;
Отдельные вопросы локализации документации
Для локализации документов у нас применяется открытое ПО Weblate, которое интегрируется с Git и позволяет выполнять локализацию как обычных текстовых файлов, так и json-файлов и др. Важно, что данное ПО работает по системе «память перевода» и позволяет автоматизировать и ускорить процесс перевода за счет накопления базы готовых сегментов текста, которые потом программными средствами вставляются в текст. Это весьма актуально для технических текстов, где содержится большой объем повторяющихся блоков и наименований.
Ну и не без ложечки дегтя
«Классно!» — скажете вы и будете бесконечно правы. Удобный модный формат с автоматизацией большинства функций обработки текста, быстрый процесс передачи и доставки заказчику, версионность — что может быть лучше?! Мы уже победили. Надо только все корректно оформить.
Не тут-то было. Мы общались с представителями разных компаний, которые уже применяют Docs-as-code или только внедряют его в каждодневную практику, и конечно же, все они сталкивались в процессе внедрения с различными трудностями. Мы не исключение. Если суммировать. то можно прийти к пониманию, что трудность всего одна: для перехода на Docs-as-code нужно дозреть.
Да, все классно: быстро, удобно и легко. Но Docs-as-code — это не просто система документации, это нечто более близкое к философии, которая требует в первую очередь строгой внутренней дисциплины, выстроенных бизнес-процессов и, главное, желания улучшить жизнь самим себе. А для этого требуется, как сейчас модно говорить, выйти из зоны комфорта и встать на путь постоянного развития.
С одной стороны, техническому писателю удобно работать по старой системе: сидишь себе спокойно, правишь рисунки в тексте — и время идет, рабочее, между прочим, и зарплата капает. А тут брось все это, изучи что-то новое, да еще освободи 70 % своего рабочего времени. И чем потом это время занимать? Конечно, работой над качеством документации, а это сложнее. С другой стороны, есть разработчик, он всегда занят, у него тысяча задач. Когда ему заниматься рисованием схем и объяснением писателю, а что же, собственно, его сервис делает и как. Конечно, времени нет. А еще есть руководитель проекта, которому в рамках нового подхода придется придумывать, как и когда встроить документирование в процесс работы.
Кроме того, у многих компаний, растущих методом слияний и поглощений, есть наследство из практиков старой закалки, которым требуется время на адаптацию к новой корпоративной культуре и которые не всегда легко принимают новые правила.
Создание и развитие хорошего продукта всегда идет параллельно с развитием команды, его создающей, а это включает также улучшение процессов разработки и документирования. Подход Docs-as-code этому способствует, и наша команда разработки ZIIoT зашла достаточно далеко в его применении, чтобы оценить все плюсы. Рапортовать о завершении этого пути пока рано, но мы работаем над этим.
Docs as Code
Технологии технического авторинга и документирования
Размеры указателей
Если говорить о печатаемых документах, то количество страниц в указателе часто напрямую указывает на качество отработки документа.
В технической документации не редкость, чтобы указатели занимали до 10 % от основного объема текста (то есть для документа из 50 страниц текста указатель будет размером в 5 страниц). Конечно, размер зависит и от плотности набора: в две или в три колонки, размер шрифта, соподчиненные термины могут идти списком, а могут набираться в подбор.
В сложных руководствах указатель достигает 25 % процентов текста. В одной из популярных книг я прочитал, что в руководстве по текстовому редактору WordStar 1989 года размер индекса составлял 17 %; на одну страницу текста приходилось 15 записей в индексе (!).
Переносы в DITA (Oxygen XML)
На просторах интернета не так много информации о том, как включить переносы в PDF-файлах, создаваемых в Oxygen XML через DITA Open Toolkit (DITA-OT) и FOP.
Извлекаем fop-hyph.jar в папку C:\Program Files\Oxygen XML Editor 20\frameworks\dita\DITA-OT2.x\plugins\org.dita.pdf2.fop\lib или аналогичную в зависимости от битности и операционной системы (требуются права администратора), или извлекаем тот же файл в любую другую папку по своему желанию.
В настройках сценария трансформации DITA-OT переходим на вкладку Advanced и нажимаем кнопку Libraries.
В открывшемся диалоговом окне нажимаем кнопку Add, находим в файловой системе fop-hyph.jar и выбираем его. Полный путь к этому файлу добавляется в диалоговое окно, и теперь fop-hyph.jar будет загружаться вместе с остальными файлами FOP (он добавлен к переменной окружения CLASSPATH ).
В настройках оформления соответствующего элемента DITA, слова в котором вы хотите переносить, нужно прописать что-то вроде
Тэг, текст внутри которого предлагается переносить, должен быть помечен как xml:lang=»ru» (иначе как FOP узнает, какие переносы взять? только когда имя языка совпадает с именем xml-файла внутри fop-hyph.jar ).
Индексы
Никогда не мог понять, как можно выпустить документацию объемом больше 20 страниц без указателей. За такое должна быть предусмотрена какая-то ответственность; желательно изолировать всех причастных к этому от общества на некоторое время.
На одном из мест работы на вопрос «как так», мне сказали — «не нужно». 150+ страниц в MS Word на каждый документ — и все без индексов (оглавление не в счёт). Если такую документацию печатать (что является обычным требованием для госконтракта), то единственный возможный исход для такой документации — быть положенной в шкаф, а через год быть отправленной на помойку. Несколько сотен страниц комплекта документации, помноженные на 2 — в мусор.
Техническую документацию не читают от и до. К технической документации обращаются, чтобы выполнить задачу. Для выполнения задачи информацию нужно найти, и найти быстро. Если информацию найти невозможно, её всё равно что нет.
Электронная версия в MS Word ситуацию на самом деле спасает не особо. Для того, чтобы что-то найти, нужно знать, какое слово задать в качестве поискового, а для этого нужно быть знакомым с терминологией авторов, то есть необходимо потратить время на чтение самого документа. Глоссарии могли бы спасти ситуацию, но беда в том, что и глоссарии часто убоги до невозможности. По сути, ничто кроме индексов не способно дать обзор терминологии и внутренних связей документа. Поисковые механизмы в веб-справке страдают от тех же родовых травм, что и файлы. По сути, без человеческого вмешательства, которое способно извлечь смысл из текста, средства (то есть электронная форма) не спасают.
В книге, например, про собак, может быть несколько страниц, посвящённых питанию щенков. Автор будет использовать фразы «собаку следует кормить», «собака возрастом до полугода ест …». Но никто, кроме человека, не поставит в указатель соподчиненные термины «щенки: питание».
Основные качества
Технический писатель — лицо, которое должно обладать навыками детектива, следователя, а в отдельных случаях даже инквизитора.
У меня сложилось ощущение, что требование «чтобы по ГОСТ» автоматически означает средненькое качество документации и много трудозатратной бестолковой возни с этой документацией в офисном текстовом редакторе.
Реальному пользователю продукта документация по ГОСТ не нужна; ему нужно удобно, информативно, быстро. Это справка в CHM или справка непосредственно внутри программного обеспечения, либо PDF или HTML. Детали оформления пользователю обычно не важны, если это оформление хорошее. Важны они только для государственного заказчика, которому важно чтобы документация соответствовала формальным оформительским критериям. Что важнее всего, государственный заказчик документацию не читает, или читает только тогда, когда нужно найти недостатки в результатах выполненных работ. Те государевы люди, которые такую документацию читают, влияния на процесс, как правило, не оказывают.
Для рыночного продукта документация — часть продажной стратегии; я не уверен, что куплю продукт, если не ознакомлюсь с его опубликованной документацией и не буду убеждён в наличии нужного функционала до мелочей. Если же компания ориентирована на государственного заказчика, то документация — не слишком-то значимая часть результата. А если документация не значима, то и затраты на неё должны быть минимальны как с точки зрения стоимости инструментов, так и с точки зрения затрат на персонал. В переводе на русский — Microsoft Word и оплата уровня секретаря. Отсюда и требования типа «владение MS Office».
Когда же возникают проблемы, этому персоналу приходится корпеть над исправлением документации сверхурочно, но во множестве компаний в нынешней России практика оплаты сверхурочной работы не прижилась.
MS Word & XSLT
Для тех несчастных, кто застрял в работе с MS Word, есть возможность хотя бы часть информации хранить во внешних источниках и вставлять её при помощи поля INCLUDETEXT: < INCLUDETEXT "C:\\temp\\data.xml" \c XML \t "C:\\temp\\table.xsl" >.
Пример данных data.xml :
Пример стиля table.xsl :
На выходе XML трансформируется в таблицу без оформления.
О Markdown
Markdown не самый плохой язык псевдоразметки, но для нормальной работы технического писателя малопригоден. Для меня основная его проблема — бедность внутритекстовой разметки.
Инструменты технического писателя
В описаниях вакансий технических писателей часто мелькает «Владение инструментами технического писателя: Word, Visio …». Очень хочется высказаться — это не инструменты технического писателя. По крайней мере, эти инструменты можно назвать инструментами технического писателя наравне с Блокнотом и штатными средствами рисования.
Настоящие инструменты технического писателя — инструменты для XML-авторинга и написания XSL-стилей, просто текстовые редакторы (я остановился на Neovim), инструменты для сборки из исходников в целевой формат, инструменты версионного контроля для хранения исходных текстов документации и изображений к ним, инструменты генерации диаграмм по исходному коду и инструменты для рисования в SVG (потому что SVG можно хранить в CVS и сравнивать, а растры сравнивать сложнее; растры можно сделать из векторов программно в нужном размере в процессе сборки документации.
Богатство возможностей MS Word создает обманчивое впечатление наличия нужной функциональности, однако при попытке начать использовать что-то из этого достаточно быстро выясняется, что функциональность куцая, недоработанная и иногда с ошибками, а использовать — себе дороже. При подготовке комплекта более чем из десятка документов работа превращается в ад. MS Word не позволяет работать над самим текстом, требуя тратить много времени на его оформление, особенно если части документа пришли от аналитиков, девопсов или программистов.
Пройдёмся по некоторым моментам с оговоркой о том, что VBA (в отличие от, например, Lua) для преодоления некоторых из высказанных претензий учить явно не стоит.
Docs as Code: введение в предмет
В последние несколько лет в среде технических писателей все больше на слуху концепция Docs as Code. Если вы раньше не сталкивались с этим термином, он обозначает подход к разработке технической документации с использованием тех же инструментов и процессов, что и написание кода. Если DocOps это про процессы и коллаборацию, то Docs as Code — про инструментарий, при помощи которого мы несмотря ни на что. Мы выбрали этот подход, когда создавали портал документации Plesk.
В этой статье я кратко расскажу, что такое Docs as Code и зачем оно нужно, а затем дам несколько советов относительно того, как это чудо враждебной техники внедрять, сдобрив всю историю рассказами о тех граблях, на которые мы наступили, топая в светлое будущее. Я старался писать такую статью, которая пригодилась бы мне в 2017 году, когда мы эту кашу заваривали.
Акт 1: Теория
Давным-давно, в далёкой-далёкой галактике…
Начнем “от противного”. Чтобы лучше понять преимущества Docs as Code, посмотрим, как документацию писали (а много где и продолжают писать) мои коллеги в компаниях по всему миру. Как правило, выглядит это так:
Документацию пишут и поддерживают технические писатели и только они.
Для разработки и публикации используются специализированные проприетарные инструменты, такие как MadCap Flare, Adobe RoboHelp, или Author-it. Реже — Wiki или Confluence.
Технические писатели работают обособленно. Что происходит у них в отделе, никто в конторе не знает и особо этим не интересуется. Взаимодействие на уровне «разработчик заметил ошибку в примере кода и завел баг в Jira», так как с инструментами технических писателей разработчик не знаком и доступа туда, где хранятся доки, у него нет.
Окей, в чем недостатки status quo? Их несколько:
Отсутствие интереса к документации у большинства сотрудников. Хороша документация разрабатываемых продуктов или плоха — никто не знает, и никому до этого нет дела. Не мой цирк, не мои обезьяны.
Конечно, ни один из этих недостатков не является фатальным. Документация создавалась и еще долгие годы будет создаваться при помощи традиционных подходов и инструментов. Однако, если есть альтернатива, важно знать, в чем она заключается и чем она лучше. Что может нам предложить Docs as Code? Давайте узнаем вместе.
Дивный новый мир
Docs as Code — это подход к разработке технической документации, который выглядит следующим образом:
Документация пишется не в плейнтексте и не в формате WYSIWYG, а на языке разметки (например, Markdown, reStructuredText, Asciidoc).
Документация хранится в репозитории Git.
Документация собирается в нужный формат при помощи генератора статических сайтов (Sphinx, Hugo, Jekyll, MkDocs). Форматов может быть сразу много: HTML, PDF, DOCX и так далее.
Документация пишется и обновляется коллаборативно.
К чему эти сложности?
Резонный вопрос. Какую головную боль лечит Docs as Code и в чем его преимущества перед классическим подходом? Преимущества есть, и их немало:
Docs as Code использует знакомые разработчикам процессы и инструменты, что помогает вовлечь их в процесс создания документации. Это может быть большим подспорьем, если в вашей организации нет выделенного технического писателя и разработкой документации для продукта занимаются сами разработчики. Чудес, правда, ждать не стоит. Для того, чтобы “и все заверте…”, скорее всего, придется терпеливо приучать разработчиков: “Василий, смотри, вот ты десять минут заводил баг в Jira, заполнял все необходимые поля и расписывал по шаблону действительность/ожидания только для того, чтобы мы ‘в лоб’ заменили на ’по лбу’. А что бы было просто не кинуть нам пулл реквест? Быстрее и проще же.”
Использование репозиториев Git и связанных с ними процессов обеспечивает возможность поддерживать документацию для разных версий продукта, облегчает коллаборацию между сотрудниками, позволяет отслеживать авторов внесенных изменений, и дает возможность быстро откатить эти изменения, если нужно. До начала использования Docs as Code у меня в практике был случай, когда я, неправильно сориентировавшись в обстановке, дал сотруднику задачу, которую тот выполнял полдня. Через пару часов выяснилось, что внесенные изменения нужно откатить, чем я лично и занимался до самого вечера. Сейчас подобный конфуз решился бы за несколько минут.
В отличие от проприетарных инструментов для разработки документации, функциональность инструментов Docs as Code безгранично расширяема и позволяет создать настолько мощную (или, наоборот, простую и дешевую) систему, насколько нужно именно вашей организации.
Проприетарные инструменты для разработки документации требуют покупки одной или нескольких лицензий (зачастую весьма дорогих). Весь же цикл разработки документации по методологии Docs as Code можно выстроить при помощи свободного программного обеспечения. Это также порадует тех, кто отказывается от использования проприетарного ПО из идейных соображений.
Хотите страшную сказку на ночь? Я расскажу, как было у нас до того, как в Plesk появился Docs as Code. Мы использовали продукт под названием Author-It, и публикация документации с его помощью выглядела так:
Делаешь выгрузку HTML. Это могло занять от пяти минут до часа, в зависимости от размера гайда.
Обрабатываешь полученную россыпь файлов кастомной тулзой, накладывающей стили и брендинг.
Пакуешь все это дело в архив и заливаешь по FTP на сервер.
Запускаешь сборку и ждешь еще полчасика. Молишься, чтобы не упало. Если упадёт, надо перезапускать.
Всё это счастье происходило при каждой публикации. Даже если ты поправил опечатку в одну букву. Это был неописуемо нудный процесс, жравший непристойное количество времени и часто приводивший к ошибкам. Забыл накатить стили перед публикацией? GOTO 20. Забыл накатить стили и уже успел удалить сгенерированные Author-it html-ки? GOTO 10. Теперь же наша документация собирается и публикуется по мерджу пулл реквеста автоматически. Автоматически, Карл! Пока не попробуешь сам, не поймешь, насколько же это круто! А сэкономленное время и внимание можно пустить на решение интересных задач.
Подводные камни
Отсутствие готовой, “коробочной” версии продукта. Все инструменты, нужные для Docs as Code, доступны, но запускать и настраивать систему вам придется самостоятельно. Будьте готовы к тому, что создание, обслуживание и совершенствование системы публикации документации потребует времени и технической экспертизы.
Отсутствие “off the shelf” решения подразумевает и отсутствие технической поддержки. Если что-то пошло не так, некому завести срочный тикет. Придется разбираться самим при помощи комьюнити.
Вашим техническим писателям нужно будет освоить работу с Git хотя бы на базовом уровне (git checkout/pull/commit/push + разрешение конфликтов при слиянии). Поначалу с этим возникнут трудности, и производительность может пострадать.
Использовать языки разметки может быть не так удобно людям, привыкшим к WYSIWYG, особенно когда дело доходит до вставки иллюстраций и создания таблиц.
Антракт
Теперь вы знаете, что такое Docs as Code, и дальше рекомендуется читать, только если вам интересно не только “что”, но и “как”. Наше путешествие к Docs as Code началось в 2017 году. У нас было много энтузиазма и мало практического опыта, поэтому мы провели в пути дольше, чем планировали, и набили немало шишек. Об этом и пойдет речь дальше.
Но сперва я сделаю еще один реверанс. Прежде чем читать про “как”, давайте подумаем про “зачем”. Docs as Code в тренде, но не стоит бросаться внедрять хайповую технологию, не задав себе вопрос “чтобы что?” В нашем случае ответ выглядел следующим образом:
Нам нужна была поддержка версионирования, а Author-It не мог в него от слова “совсем”. Author-It позволял хранить и публиковать документацию только для одной версии продукта. Если нужно было внести изменения в документацию для более ранней версии Plesk, приходилось править HTML руками.
Также хотелось оставить в прошлом некоторые заскоки Author-It. Например, он позволял молча и без подтверждения выкинуть из структуры гайда топик со всеми его подтопиками. И возможности откатить эту операцию при помощи Ctrl + Z не было. Сами топики при этом не удалялись, страдала только структура, и в теории ее можно было воссоздать руками. На практике было быстрее и проще зайти по RDP на виртуальную машинку, где крутилась серверная часть Author-It, развернуть более старый бэкап базы MSSQL, в которой Author-It хранил всю информацию, выгрузить неповрежденную структуру гайда в XML, снова подключить актуальную базу, удалить гайд, структура которого пострадала, а затем импортировать его из XML. Не шучу, время от времени приходилось заниматься подобным шаманством.
Мы рассматривали различные варианты нового механизма публикации, но все они по тем или иным параметрам не устраивали. Wiki не позволяла сделать версионирование и не имела наглядной структуры и оглавления. Confluence не имел внятной поддержки локализации кроме кошмарного варианта “давайте сделаем отдельный спейс для каждой комбинации ‘версия продукта + язык’”. Смотрели в сторону MadCap Flare, но в итоге отказались, решив, что нет никакой гарантии, что впоследствии не вылезут какие-то проблемы, которые снова заставят переезжать. В итоге выбор пал на Docs as Code как на вариант, обещавший в перспективе удовлетворить всем нашим требованиям.
Акт 2: Практика
Внедряем Docs as Code
Что же, вы решили внедрить в своей организации подход Docs as code. С чего начать?
Сформируйте список требований
Если вам кажется, что это долго и не очень-то и нужно, представьте, что вы ввели новый инструмент в эксплуатацию, потратив на это время, усилия, и деньги. А затем обнаружили, что он не обладает той или иной возможностью, необходимой для работы, потому что на этапе планирования о ней никто не вспомнил, и в требованиях она не была зафиксирована. “Что, таблички? Нет, таблички нельзя создавать. Так ведь об этом не просил никто, вот мы поддержку табличек и не сделали”. Не очень история, правда?
Планируйте
Прежде чем начинать работу по внедрению, тщательно спланируйте ваш проект, разберитесь в существующих технологиях и инструментах. Эта “грабля” нам довольно больно стукнула по лбу. Мы начинали внедрение Docs as code силами отдела технической документации. Когда стало ясно, что нам не хватает где-то ресурсов, а где-то экспертизы, пришлось обратиться за помощью к коллегам. Мы обсудили с ними цели и план работ и пришли к выводу, что некоторые из выбранных инструментов лучше заменить. В итоге часть уже проделанной работы оказалась на свалке.
Важный момент: если вы не собираетесь делать всё своими собственными мозолистыми руками, а планируете привлечь для внедрения другую команду или нанять разработчиков со стороны — коммуницируйте, коммуницируйте и еще раз коммуницируйте. Пока не стошнит, если необходимо. Не дав себе труда убедиться в том, что исполнитель точно понимает ваши потребности, вы рискуете получить на выходе нечто, как будто сошедшее с известной смешной картинки:
«Да чего тут рассусоливать, всем все понятно, поехали!»
Пользоваться таким “чудом” может быть неудобно, а в худшем случае и вовсе невозможно.
Документируйте
Не ленитесь документировать вашу систему Docs as Code. Особенно если вы делаете что-то более сложное, чем “один репозиторий Git + генератор статических сайтов в стандартной комплектации”. Да, на это всегда не хватает времени, но поверьте, усилия окупятся сторицей. Через пару лет вам не нужно будет морщить лоб, пытаясь разобраться, как же оно тут все устроено. “Это что? Как оно работает? Кто писал этот код? Ах, человек уже год как уволился. ” Чем подробнее вы опишете детали реализации вашего решения, тем проще его потом будет поддерживать и модернизировать. Если вы решили заказать создание системы Docs as Code на стороне, обязательно включите ее документирование в список задач, необходимых для выполнения.
Решите, в каком формате вы хотите публиковать документацию
HTML? PDF? DOC? Все из вышеперечисленного? В зависимости от ответа на этот вопрос вам может лучше подойти тот или иной язык разметки. Например, из reStructuredText можно публиковаться во все три вышеприведенных формата, а “классическая” интерпретация Markdown конвертируется только в HTML.
Выберите язык разметки
Markdown
Из двух рассматриваемых языков разметки этот более простой, но и более ограниченный в плане форматов, в которые он может быть сконвертирован без дополнительных приседаний. Существует несколько имплементаций Markdown, ни одна из которых не является канонической. Например, GitHub Flavored Markdown обладает более широкими возможностями по сравнению со своим “предком”. Выбрав наиболее подходящую для ваших нужд имплементацию Markdown, убедитесь, что используемый вами парсер корректно превращает ее в HTML.
reStructuredText
Более мощный язык разметки, но и более капризный. В нем сложнее писать и проще допустить ошибку в синтаксисе (во всяком случае, пока не привыкнешь). Например, чтобы документ в reStructuredText не собрался корректно, достаточно пропустить или поставить лишний пробел или перенос строки. Большое преимущество reStructuredText в его расширяемости — при помощи плагинов вы можете научить систему публикации распознавать и корректно отображать необходимые вам сущности (ссылки, таблички, вставки и так далее) в HTML.
Пример из недавнего — нам нужно было добавить возможность вставлять выделенный рамкой текст. Мы используем такое выделение для краткого описания содержания статей документации. Так пользователь может за несколько секунд понять, в нужную ли статью он зашел. Изначально подобного функционала у нас не было. Но за несколько часов у нас появилась возможность добавлять подобные вставки при помощи такого форматирования:
Собираем HTML и видим вот такое:
Какой язык разметки используется в Plesk? Мы подумали и решили:
Это не шутка — мы действительно используем на нашем портале документации и reStructuredText и Markdown. Зачем? Все просто: мы используем разные языки разметки для решения разных задач с разными требованиями:
reStructuredText используется для написания документации. Для этой задачи нам в первую очередь важны богатые возможности форматирования, а также расширяемость.
Чтобы понять, какой язык разметки лучше подходит для ваших нужд, можно начать с этой статьи в Wikipedia. В ней рассматриваются сравнительные характеристики различных легковесных языков разметки, а также примеры синтаксиса.
Выберите инструмент для публикации
Вы определились с языком разметки. Пора выбрать инструмент, при помощи которого вы будете документацию публиковать. Вариантов несколько, но в этой статье для начинающих я хотел бы сфокусировать внимание на четырех: Hugo, Jekyll, Sphinx и MkDocs. По сути, все они являются генераторами статических сайтов. Hugo и Jekyll больше ориентированы на блоги, а Sphinx и MkDocs специально заточены для создания документации и обладают большим количеством полезных в этом деле фич “из коробки”. Все четыре инструмента популярны, широко используются, поддерживаются и имеют активное комьюнити.
Если выбор вас пугает, не переживайте. На самом деле, часть опций вы отсекли еще на предыдущих шагах. Генераторы статических сайтов поддерживают, как правило, один-два языка разметки. Если на предыдущем шаге вы выбрали reStructuredText (“расширяемость — наш выбор, а синтаксис выучим”), то ваш главный кандидат — Sphinx. И ваш выбор инструментов будет куда шире, если вы проголосовали за Markdown (“мы не хотим возиться с reStructuredText и разбираться, почему после трех коммитов, призванных исправить ошибки форматирования, HTML собирается вкривь и вкось”).
Сделайте красиво
Ну или хотя бы так, чтобы сайт документации не выбивался из общего стиля вашей организации. Каждый из рассматриваемых в статье инструментов поддерживает использование тем, меняющих внешний вид создаваемых ими страниц. Есть широкий ассортимент доступных и бесплатных тем. Если у вас нет возможности сделать оформление под себя самостоятельно или заказать подобную услугу, имеет смысл ознакомиться с ассортиментом доступных тем заранее, чтобы потом не вздыхать — “эх, нам бы то же самое, но с перламутровыми пуговицами”.
Что насчет существующего контента?
Определитесь с версионированием
Если вы разрабатываете SaaS продукт или агрессивно пушите пользователей обновляться, поддержка версионирования вам вряд ли потребуется. Но что делать, если вам нужно поддерживать и предоставлять пользователям документацию для двух или более версий продукта?
Дешевое решение — паковать собранную документацию для старых версий продукта в архивы и делать их доступными для скачивания. Мы так поступаем с документацией для ушедших в EOL много лет назад версий Plesk, которыми уже почти никто не пользуется. Но это неудобно для пользователя. Клиент на старой версии продукта вряд ли сможет найти вашу документацию при помощи Google или другой поисковой системы (для справки: на docs.plesk.com органический поисковый трафик составляет более половины посетителей).
Нам было важно дать клиентам доступ к документации последней и предпоследней версий Plesk (Onyx и Obsidian) и сделать так, чтобы отдельная страница со своим контентом и URL была у обеих версий. Мы реализовали это следующим образом: в каждом репозитории Git, содержащем исходники того или иного руководства, есть несколько веток. Каждая ветка содержит исходные файлы для той или иной версии продукта, что позволяет вносить изменения в документацию, например, для Plesk Obsidian, при этом никак не затрагивая документацию для Plesk Onyx. Есть и недостаток: когда нужно обновить документацию для всех версий продукта сразу, приходится делать коммиты в каждую ветку по очереди, что тоже занимает время.
Ду ю спик инглиш?
Возможно, вам понадобится переводить вашу документацию на иностранные языки для ваших клиентов. Если так, то стоит заранее подумать о том, как вы будете работать с переводами.
msgid «You can choose to:»
msgstr «Folgende Optionen stehen zur Verfügung:»
Автоматизируй это
-Василий, почему релиз ноты еще не на продакшене? Два часа как вышло обновление, клиенты жалуются (у нас были подобные случаи и клиенты действительно жалуются)!
-А, черт, я закоммитил, а запустить сборку забыл 🙁
Пересобирается сам портал документации, включая релиз ноты, FAQ и все прочие находящиеся на нем страницы.
Собранная документация разворачивается на сервере.
Сети доставки содержимого подается команда сбросить кэш.
Здесь есть еще одна тонкость. Кроме Plesk, мы публикуем множество расширений к нему, и каждый новый выпуск каждого из расширений тоже сопровождается своими релиз нотами. Они становятся доступными к сборке документации как только попадают в основную ветвь, поскольку для них время публикации не особо критично. Но для обновлений самого Plesk релиз ноты должны появиться в публичном доступе одновременно с выходом обновления, иначе сразу начинают сыпаться запросы от клиентов («Мой Plesk автоматически обновился, где я могу прочесть об изменениях?», «Я вижу на портале документации релиз ноты для обновления Plesk, как мне его поставить?»). Во избежание подобных ситуаций, релиз ноты для основного продукта становятся доступными к сборке документации и публикуются строго в рамках публикации обновления Plesk.
Заключение
Нужен ли вам Docs as code? Зависит от. Если у вас небольшая компания, несложный продукт, устоявшиеся процессы и дюжина страниц документации, которые вы обновляете раз в квартал — пожалуй, выхлоп не окупит затрат на внедрение. Если же вас заинтересовали описанные в моей статье возможности, или вы просто любите быть на острие прогресса — почему нет? Просто заранее вдумчиво спланируйте вашу будущую систему Docs as code исходя из ваших уникальных потребностей, и я уверен — вы не пожалеете 🙂