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

В этой статье я кратко расскажу, что такое Docs as Code и зачем оно нужно, а затем дам несколько советов относительно того, как это чудо враждебной техники внедрять, сдобрив всю историю рассказами о тех граблях, на которые мы наступили, топая в светлое будущее. Я старался писать такую статью, которая пригодилась бы мне в 2017 году, когда мы эту кашу заваривали.

(N.B. Сразу оговорюсь, что эта статья - обзорная, в ней нет огрызков конфигов или примеров кода. Если вы уже знаете теорию и ищете, как конкретно пропатчить KDE2 под FreeBSD, статья может быть вам не очень интересна).

Акт 1: Теория

Давным-давно, в далёкой-далёкой галактике

Начнем от противного. Чтобы лучше понять преимущества Docs as Code, посмотрим, как документацию писали (а много где и продолжают писать) мои коллеги в компаниях по всему миру. Как правило, выглядит это так:

• Документацию пишут и поддерживают технические писатели и только они.

• Для разработки и публикации используются специализированные проприетарные инструменты, такие как MadCap Flare, Adobe RoboHelp, или Author-it. Реже Wiki или Confluence.

• Технические писатели работают обособленно. Что происходит у них в отделе, никто в конторе не знает и особо этим не интересуется. Взаимодействие на уровне "разработчик заметил ошибку в примере кода и завел баг в Jira", так как с инструментами технических писателей разработчик не знаком и доступа туда, где хранятся доки, у него нет.

Окей, в чем недостатки status quo? Их несколько:

• Отсутствие интереса к документации у большинства сотрудников. Хороша документация разрабатываемых продуктов или плоха никто не знает, и никому до этого нет дела. Не мой цирк, не мои обезьяны.

• Плохая коллаборация. Чтобы исправить опечатку в документации, разработчик или сотрудник поддержки должен написать письмо или завести баг, и станут ли они это делать - бабушка надвое сказала. Это лишний геморрой, а у них и так работы по горло. Процесс совместного ревью также затруднен. Чтобы сделать ревью документа, его нужно выгрузить в гуглдок или файл MS Word, отправить по почте нескольким людям, принять от них комментарии в документах и потом свести их воедино. Ревьюеры не видят комментарии друг друга, делают двойную работу и противоречат друг другу. Это неудобно и техническому писателю, и проверяющему.

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

• Стоимость. Лицензия на широко используемый продукт MadCap Flare обойдется вам в $149 на человека в месяц. Хотите воспользоваться облачным решением от MadCap? Готовьте $300. Незначительная сумма для большой организации. Большой удар по карману для маленькой фирмы или стартапа, еще не нашедшего стабильный источник финансирования.

Конечно, ни один из этих недостатков не является фатальным. Документация создавалась и еще долгие годы будет создаваться при помощи традиционных подходов и инструментов. Однако, если есть альтернатива, важно знать, в чем она заключается и чем она лучше. Что может нам предложить 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 безгранично расширяема и позволяет создать настолько мощную (или, наоборот, простую и дешевую) систему, насколько нужно именно вашей организации.

• Значительное (в несколько раз) сокращение временных затрат на рутинные операции. Публикация при помощи проприетарных инструментов запускается вручную и выдает через какое-то время готовый документ в формате .html или .pdf. Разместить его онлайн ваша забота. В результате имеем долгие, многоступенчатые процедуры публикации, требующие ручных действий на каждом из шагов. Публикация же с помощью Docs as Code может быть сведена к выполнению одной команды или даже полностью автоматизирована.

• Проприетарные инструменты для разработки документации требуют покупки одной или нескольких лицензий (зачастую весьма дорогих). Весь же цикл разработки документации по методологии Docs as Code можно выстроить при помощи свободного программного обеспечения. Это также порадует тех, кто отказывается от использования проприетарного ПО из идейных соображений.

Хотите страшную сказку на ночь? Я расскажу, как было у нас до того, как в Plesk появился Docs as Code. Мы использовали продукт под названием Author-It, и публикация документации с его помощью выглядела так:

1. Делаешь выгрузку HTML. Это могло занять от пяти минут до часа, в зависимости от размера гайда.

2. Обрабатываешь полученную россыпь файлов кастомной тулзой, накладывающей стили и брендинг.

3. Пакуешь все это дело в архив и заливаешь по FTP на сервер.

4. Запускаешь сборку и ждешь еще полчасика. Молишься, чтобы не упало. Если упадёт, надо перезапускать.

Всё это счастье происходило при каждой публикации. Даже если ты поправил опечатку в одну букву. Это был неописуемо нудный процесс, жравший непристойное количество времени и часто приводивший к ошибкам. Забыл накатить стили перед публикацией? GOTO 20. Забыл накатить стили и уже успел удалить сгенерированные Author-it html-ки? GOTO 10. Теперь же наша документация собирается и публикуется по мерджу пулл реквеста автоматически. Автоматически, Карл! Пока не попробуешь сам, не поймешь, насколько же это круто! А сэкономленное время и внимание можно пустить на решение интересных задач.

Подводные камни

Перечитал предыдущий абзац - звучит, как будто я этим Docs as Code торгую. Что же, у нас на руках идеальное решение? Необязательно. Как и у любого другого подхода, у него есть своя специфика и недостатки:

• Отсутствие готовой, коробочной версии продукта. Все инструменты, нужные для 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 умел выгружать топики документации в .doc, который потом высылался на ревью ПМу + разработчику + тестировщику. Сводить комментарии и изменения из нескольких вордовых файлов в один было тем еще удовольствием.

• Также хотелось оставить в прошлом некоторые заскоки 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. С чего начать?

Сформируйте список требований

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

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

Планируйте

Прежде чем начинать работу по внедрению, тщательно спланируйте ваш проект, разберитесь в существующих технологиях и инструментах. Эта грабля нам довольно больно стукнула по лбу. Мы начинали внедрение Docs as code силами отдела технической документации. Когда стало ясно, что нам не хватает где-то ресурсов, а где-то экспертизы, пришлось обратиться за помощью к коллегам. Мы обсудили с ними цели и план работ и пришли к выводу, что некоторые из выбранных инструментов лучше заменить. В итоге часть уже проделанной работы оказалась на свалке.

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

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

Документируйте

Не ленитесь документировать вашу систему Docs as Code. Особенно если вы делаете что-то более сложное, чем один репозиторий Git + генератор статических сайтов в стандартной комплектации. Да, на это всегда не хватает времени, но поверьте, усилия окупятся сторицей. Через пару лет вам не нужно будет морщить лоб, пытаясь разобраться, как же оно тут все устроено. Это что? Как оно работает? Кто писал этот код? Ах, человек уже год как уволился... Чем подробнее вы опишете детали реализации вашего решения, тем проще его потом будет поддерживать и модернизировать. Если вы решили заказать создание системы Docs as Code на стороне, обязательно включите ее документирование в список задач, необходимых для выполнения.

Решите, в каком формате вы хотите публиковать документацию

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

Выберите язык разметки

Зная задачу, проще подобрать инструмент для ее выполнения. Существует целый ряд легковесных языков разметки, но два самых популярных из них - reStructuredText и Markdown:

Markdown

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

reStructuredText

Более мощный язык разметки, но и более капризный. В нем сложнее писать и проще допустить ошибку в синтаксисе (во всяком случае, пока не привыкнешь). Например, чтобы документ в reStructuredText не собрался корректно, достаточно пропустить или поставить лишний пробел или перенос строки. Большое преимущество reStructuredText в его расширяемости при помощи плагинов вы можете научить систему публикации распознавать и корректно отображать необходимые вам сущности (ссылки, таблички, вставки и так далее) в HTML.

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

.. admonition:: summary

Hello world!

Собираем HTML и видим вот такое:

Какой язык разметки используется в Plesk? Мы подумали и решили:

Это не шутка мы действительно используем на нашем портале документации и reStructuredText и Markdown. Зачем? Все просто: мы используем разные языки разметки для решения разных задач с разными требованиями:

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

• Markdown используется для написания release notes. Мы пишем их много и часто, а требования к форматированию минимальны - болд/италик/моноспейс/кодблок/ссылки. Для этой задачи нам важнее всего простота и скорость использования.

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

Выберите инструмент для публикации

Вы определились с языком разметки. Пора выбрать инструмент, при помощи которого вы будете документацию публиковать. Вариантов несколько, но в этой статье для начинающих я хотел бы сфокусировать внимание на четырех: Hugo, Jekyll, Sphinx и MkDocs. По сути, все они являются генераторами статических сайтов. Hugo и Jekyll больше ориентированы на блоги, а Sphinx и MkDocs специально заточены для создания документации и обладают большим количеством полезных в этом деле фич из коробки. Все четыре инструмента популярны, широко используются, поддерживаются и имеют активное комьюнити.

Если выбор вас пугает, не переживайте. На самом деле, часть опций вы отсекли еще на предыдущих шагах. Генераторы статических сайтов поддерживают, как правило, один-два языка разметки. Если на предыдущем шаге вы выбрали reStructuredText (расширяемость наш выбор, а синтаксис выучим), то ваш главный кандидат Sphinx. И ваш выбор инструментов будет куда шире, если вы проголосовали за Markdown (мы не хотим возиться с reStructuredText и разбираться, почему после трех коммитов, призванных исправить ошибки форматирования, HTML собирается вкривь и вкось).

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

В Plesk для сборки документации мы используем Sphinx, а для сайта портала документации целиком - Jekyll. Это позволяет расцепить механизмы обновления непосредственно руководств и других страниц, размещенных на портале документации, например, чейнджлога или FAQ. Благодаря этому публикация release notes для новых версий продукта и его расширений занимает меньше минуты.

Сделайте красиво

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

Что насчет существующего контента?

Возможно, у вас уже есть сайт с документацией. Что же, при выборе Docs as code вам придется выбросить его или заново набивать руками? Не обязательно. Существуют решения для конвертации текстов из одного формата в другой, но с ними тоже придется разбираться. Как тут поступить зависит от объема существующей документации. Если у вас есть десяток-другой документов, возможно, будет проще, скрепя сердце, набрать их заново в выбранном языке разметки. В Plesk массив документации насчитывал приблизительно четыре с половиной тысячи документов, поэтому для нас подобный вариант не был реалистичным. В итоге мы без потерь сконвертировали всю существующая документацию из .html в .rst при помощи инструмента Pandoc.

Определитесь с версионированием

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

Дешевое решение паковать собранную документацию для старых версий продукта в архивы и делать их доступными для скачивания. Мы так поступаем с документацией для ушедших в EOL много лет назад версий Plesk, которыми уже почти никто не пользуется. Но это неудобно для пользователя. Клиент на старой версии продукта вряд ли сможет найти вашу документацию при помощи Google или другой поисковой системы (для справки: на docs.plesk.com органический поисковый трафик составляет более половины посетителей).

Нам было важно дать клиентам доступ к документации последней и предпоследней версий Plesk (Onyx и Obsidian) и сделать так, чтобы отдельная страница со своим контентом и URL была у обеих версий. Мы реализовали это следующим образом: в каждом репозитории Git, содержащем исходники того или иного руководства, есть несколько веток. Каждая ветка содержит исходные файлы для той или иной версии продукта, что позволяет вносить изменения в документацию, например, для Plesk Obsidian, при этом никак не затрагивая документацию для Plesk Onyx. Есть и недостаток: когда нужно обновить документацию для всех версий продукта сразу, приходится делать коммиты в каждую ветку по очереди, что тоже занимает время.

Ду ю спик инглиш?

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

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

Мы пошли более затратным в реализации, но куда более дешевым в использовании путем. Мы разбиваем исходные документы на английском языке на единицы перевода (заголовки, абзацы все, что с обеих сторон ограничено переносом строки). Переводы руководств на все языки хранятся в том же репозитории/ветке, что и само руководство в виде .po файлов. Содержимое их выглядит так:

#: ../../../../projects/administrator-guide/source/53231.rst:15

msgid "You can choose to:"

msgstr "Folgende Optionen stehen zur Verfgung:"

Здесь мы видим перевод единицы перевода из репозитория administrator-guide, документ 53231.rst, строка 15. В наличии как исходная строка, так и ее перевод на немецкий (всего в данном .po файле шесть таких единиц, некоторые поменьше, некоторые побольше). В итоге все содержимое документа на английском покрывается переводом. При сборке документации на немецком механизм берет исходный файл .rst и автоматически заменяет единицы перевода в нем на переведенные. Данный подход позволил нам интегрироваться с сервисом Crowdin, в котором работают наши переводчики. Они пользуются привычным им интерфейсом мы получаем переводы.

Автоматизируй это

Одно из основных преимуществ подхода Docs as code - возможность использовать инструменты непрерывного развертывания, чтобы передать связанные с публикацией рутинные операции на попечение роботов. Не пренебрегайте им. Чем чаще вы вносите изменения или публикуете новые документы, тем больше времени автоматика вам сэкономит. С тех пор, как мы внедрили автоматическую публикацию по слиянию, автоматика экономит нам минимум один-два (а зачастую и больше) человеко-часа каждую неделю, а также исключает подобные драматические сцены:

-Василий, почему релиз ноты еще не на продакшене? Два часа как вышло обновление, клиенты жалуются (у нас были подобные случаи и клиенты действительно жалуются)!

-А, черт, я закоммитил, а запустить сборку забыл :(

В Plesk мы реализовали непрерывное развертывание документации при помощи Jenkins - он уже используется для разработки и публикации самого продукта, и мы решили не изобретать велосипед. Для публикации документации и релиз нот используются разные пайплайны. Схематично выглядит это так:

1. При слиянии ветки с изменениями в основную, сервер Jenkins запускает сборку гайда, в который были внесены изменения (.rst => .html), на всех языках, на которые он переведен, а также обновляет файлы .po, которые пойдут потом на перевод. Если мы публикуем релиз ноты, этот шаг пропускается.

2. Пересобирается сам портал документации, включая релиз ноты, FAQ и все прочие находящиеся на нем страницы.

3. Собранная документация разворачивается на сервере.

4. Сети доставки содержимого подается команда сбросить кэш.

Здесь есть еще одна тонкость. Кроме Plesk, мы публикуем множество расширений к нему, и каждый новый выпуск каждого из расширений тоже сопровождается своими релиз нотами. Они становятся доступными к сборке документации как только попадают в основную ветвь, поскольку для них время публикации не особо критично. Но для обновлений самого Plesk релиз ноты должны появиться в публичном доступе одновременно с выходом обновления, иначе сразу начинают сыпаться запросы от клиентов ("Мой Plesk автоматически обновился, где я могу прочесть об изменениях?", "Я вижу на портале документации релиз ноты для обновления Plesk, как мне его поставить?"). Во избежание подобных ситуаций, релиз ноты для основного продукта становятся доступными к сборке документации и публикуются строго в рамках публикации обновления Plesk.

Заключение

Нужен ли вам Docs as code? Зависит от. Если у вас небольшая компания, несложный продукт, устоявшиеся процессы и дюжина страниц документации, которые вы обновляете раз в квартал пожалуй, выхлоп не окупит затрат на внедрение. Если же вас заинтересовали описанные в моей статье возможности, или вы просто любите быть на острие прогресса почему нет? Просто заранее вдумчиво спланируйте вашу будущую систему Docs as code исходя из ваших уникальных потребностей, и я уверен вы не пожалеете :)

Спасибо за внимание!

P.S. Хочу также сказать "спасибо" Николаю Волынкину, Дмитрию Ширяеву и Катерине Говердовской за участие в работе по созданию и наполнению нашего портала документации, а также за помощь в написании статьи.

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

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

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

Что такое хорошая документация?

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

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

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

Хорошо, допустим. А что позволяет документации выполнять задачу? Какая она, хорошая документация, и как ее создавать? Есть ряд практик, которым мы следуем, когда пишем документацию в Plesk, и сегодня я хотел бы о них рассказать. Итак...

Хорошую документацию легко найти

Времена, когда лежащий в коробке с программой мануал был единственным источником информации для пользователя, ушли безвозвратно. В наши дни каждый имеет доступ к практически неограниченному количеству информации, и у технических писателей больше нет монополии на внимание пользователя. Как бы ни была хороша ваша документация, если она занимает низкую позицию в выдаче поисковых систем, ее просто никто не прочтет. Чтобы ваша документация приносила пользу, позаботьтесь о ее находимости (findability).

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

1. Человек начинает пользоваться Plesk.

2. Человек сталкивается с затруднением.

3. Человек пытается разобраться с затруднением самостоятельно.

4. Когда желание преодолеть затруднение пересиливает нежелание тратить время на поиск помощи, человек вводит запрос в Google и открывает первую ссылку в выдаче.

Замечу, что по данным Google Search Console запросы пользователей не включают слово документация. Люди ищут plesk login, plesk install, plesk ftp и так далее. Скорее всего, запросы, по которым пользователи находят документацию вашего продукта, выглядят похоже. Чтобы пользователям было проще найти вашу документацию, важно использовать те термины и формулировки, которые они используют. Это особенно важно в случае если поисковая система на вашем сайте документации не очень хорошо производит нечеткий поиск.

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

Так же и человек хочет получить максимально полезный и информативный ответ на вопрос, затратив минимум усилий и времени. Попадая на новую страницу в Интернете, человек пробегает по ней глазами в поиске свидетельств того, что здесь он сможет найти ответ на интересующий его вопрос. Ключевые слова, заголовки, ссылки, и так далее и формируют тот самый информационный запах. Компания Nielsen Norman Group провела исследование среди пользователей и выяснила, что если в течение первых десяти секунд посетитель не обнаруживает на странице сильный информационный запах, он скорее всего уйдет с нее и продолжит поиск в другом месте.

Как же привлечь внимание пользователя за те десять секунд, что у нас есть? Отличная практика разместить в самом начале каждого раздела краткое (не больше трех-четырех предложений) описание его содержания, в идеале оформив его так, чтобы оно визуально отличалось от остального текста и бросалось в глаза. Сюда же можно добавить ссылки на схожие по смыслу разделы, чтобы облегчить дальнейший поиск пользователям, оказавшимся не там, где они планировали. Вот как может выглядеть такое описание:

В этом разделе вы узнаете, как создать новый FTP аккаунт в Plesk. Если вы хотите узнать, как изменить логин или пароль существующего FTP аккаунта, пройдите по ссылке.

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

Хорошую документацию легко понять

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

В работе я руководствуюсь высказыванием Антуана де Сент-Экзюпери: Совершенство достигнуто не тогда, когда нечего добавить, а тогда, когда нечего убрать. Когда готов первый черновик документации для новой фичи, первое, на что я смотрю можно ли сделать текст проще и короче. Что помогает в этом?

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

• Простые предложения.

• Короткие (4-6 предложений) абзацы.

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

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

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

Некоторое время назад я искал технического писателя в свою команду. В тестовом задании, предлагавшемся соискателям, была просьба написать короткую инструкцию, объясняющую, как установить расширение в Chrome. Один из кандидатов снабдил каждый шаг полноразмерным снимком экрана, что раздуло небольшую инструкцию на пару страниц. Чем это плохо? Напомню, что попадая на новую страницу, человек не начинает вдумчиво читать, он пробегается по ней глазами. Большой объем вкупе с обилием иллюстраций отпугивает, несложная процедура кажется чем-то сродни запуску ядерного реактора. Сложилось ощущение, что у соискателя были какие-то установки ("снимки экрана это хорошо"), но не было понимания, что любым инструментом нужно пользоваться к месту и в меру. Отбор он не прошел.

Хорошая документация описывает сценарии

Классический подход к документированию интерфейсов подразумевает последовательное описание индикаторов и элементов управления, размещенных на том или ином экране. Типичный пример снимок экрана с цифрами-выносками, а под ним нумерованный список, перечисляющий все, что пользователь и так видит. Введите имя пользователя в поле Имя пользователя. Нажмите Ok, когда захотите закончить операцию.

Проблема этого подхода в том, что он не отражает то, как люди пользуются документацией. Если когда-то и были времена, в которые человек, купив программу, внимательно читал от корки до корки лежащий в коробке мануал, они остались в прошлом. Никто не читает документацию, чтобы узнать, что делают все кнопки на экране Создать домен. Пользователи обращаются к документации, когда у них возникают затруднения с выполнением какого-то реального сценария, связанного с использованием продукта (создать почтовый ящик, защитить сайт SSL сертификатом, и так далее).

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

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

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

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

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

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

• Как мне создать почтовый ящик?

• Как мне поменять пароль?

• Как мне удалить базу данных?

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

Хорошая документация самодостаточна

При написании документации в Plesk мы руководствуемся принципом Every page is page one (EPPO) почерпнутым из одноименной книги Марка Бейкера. Чтобы понять его суть, давайте подумаем о том, как люди читают печатные книги, и как ищут информацию в Интернете:

• Человек, читающий печатную книгу, начинает чтение с первой страницы и читает последовательно, постепенно создавая контекст. В пятой главе нет нужды расшифровывать термин, с которым читатель познакомился во второй.

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

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

Приведу пример. Некоторое время назад для того, чтобы защитить сайт SSL сертификатом, нужно было выполнить в панели Plesk следующие действия:

1. Сгенерировать запрос на подпись сертификата (certificate signing request) и купить сертификат в центре сертификации (certificate authority).

2. Загрузить полученный сертификат в хранилище.

3. Выбрать загруженный сертификат в настройках веб сервера.

Номинально, каждый из приведенных выше пунктов можно рассматривать как отдельный сценарий, но подобный подход может ввести пользователя в заблуждение, так как для достижения цели (сайт защищен SSL сертификатом) нужно выполнить все вышеприведенные действия в правильной последовательности.

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

Хорошая документация достоверна

Иными словами, она точно отражает то, как продукт выглядит и работает прямо сейчас, а не полгода назад. В наше время SaaS-продуктов, коротких релиз циклов и принудительных автоматических обновлений это правило, к сожалению, нарушается все чаще. Как ни странно, этим нередко грешит документация гигантов индустрии, таких как Microsoft или Google.

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

Для того, чтобы подобного не происходило, команда технических писателей должна иметь следующее:

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

• Достаточно ресурсов, чтобы своевременно отражать эти изменения в документации.

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

Хорошая документация пишется для определенной аудитории

Еще одно явление, о котором нужно знать, чтобы писать хорошую документацию это проклятие знания (curse of knowledge). Под таким зловещим именем скрывается когнитивное искажение, заключающееся в том, что человеку информированному сложно встать на место человека неосведомленного и увидеть ситуацию его глазами. Если вы когда-нибудь произносили или думали про себя Ну-у, да это все знают, вероятно, вы были под воздействием этого искажения.

К счастью, с этим искажением можно справиться. Достаточно помнить о нем и знать, кто целевая аудитория документации, которую вы пишете, и каким багажом знаний обладает ее среднестатистический представитель. Например, если вы документируете клиент Git, можно предположить, что представителю целевой аудитории не нужно рассказывать, что такое система управления версиями или как сделать коммит, но стоит задокументировать, как настроить доступ в репозиторий по SSH ключу. А если у вас в голове возникает мысль Это, наверное, всем известно, напомните себе, что вы пишете документацию не для всех, а для конкретной аудитории с конкретными знаниями и потребностями.

Проиллюстрирую этот пункт следующим примером: несколько лет назад я получил обратную связь от двух разных пользователей на один и тот же раздел. Она звучала примерно так:

• Пользователь А: Что вы пишете, как для дураков? Разжевываете вещи, которые любому известны!

• Пользователь Б: Вы знаете, не каждый из нас гений. Пожалуйста, пишите яснее, мне ничего не понятно.

Как вы думаете, кто из них был прав? На самом деле, правы оба. Судя по всему, раздел, на который они жаловались, как раз и был написан для всех, но в итоге не смог сослужить службу никому. Он был слишком сложен для новичка, но не содержал подробностей, интересных эксперту. Как избежать подобных ситуаций? Знать, кто целевая аудитория, и писать с учетом ее потребностей. Ничего страшного, если вы получаете обратную связь только одного типа (слишком сложно или слишком просто) это означает, что жалуются люди, не входящие в ЦА (конечно, если подобных обращений не десять штук за неделю).

Хорошая документация оказывает поддержку

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

Приведу пример. В Plesk для защиты от спама используется программа под названием SpamAssassin. Одна из доступных пользователю настроек (spam filter sensitivity) управляет тем, насколько строго фильтр отсеивает входящие письма с подозрением на спам. Работает она просто: пользователь задает значение, выраженное положительным числом не больше 127. Чем меньше число, тем строже фильтр. Вот как могла бы быть описана эта настройка в плохой документации:

Введите желаемое число в поле Spam filter sensitivity и нажмите Ok.

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

Введите желаемое число (больше 0 и не больше 127) в поле Spam filter sensitivity и нажмите Ok. Чем меньше число, тем меньше вероятность того, что в ваш ящик попадет спам, и тем больше вероятность ложного срабатывания, и наоборот.

А можно ли сделать еще лучше? Как насчет такого:

Введите желаемое число (больше 0 и не больше 127) в поле Spam filter sensitivity и нажмите Ok. Чем меньше число, тем меньше вероятность того, что в ваш ящик попадет спам, и тем больше вероятность ложного срабатывания, и наоборот. Рекомендуемое значение 7, оно обеспечивает надежную защиты от спама с минимальной вероятностью ложного срабатывания и подойдет большинству пользователей.

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

Как еще можно облегчить жизнь пользователя? Не превращать его в Буриданова осла. Если продукт позволяет добиться того или иного результата несколькими путями, я не описываю их все. Я выбираю оптимальный (самый простой, самый быстрый и так далее) и рассказываю только о нем. Если же между этими путями есть разница (скажем, один быстрее, но подразумевает действия, требующие технических навыков или потенциально рискованные, например, выполнение запросов INSERT или UPDATE в базе данных), я описываю все варианты, эксплицитно указывая на различия между ними, чтобы помочь пользователю выбрать оптимальный для него вариант.

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

Заключение

Теперь вы знаете, как писать хорошую документацию по версии Plesk. Прежде чем откланяться, я хотел бы рассказать еще об одном принципе, который я также позаимствовал у Марка Бейкера. Он звучит просто Напиши одну хорошую страницу (Write one good page). Почему он кажется мне очень важным: если у вас уже есть массив документации, написанный по старинке и не соответствующий лучшим практикам, велик соблазн опустить руки. Переписать все с нуля это целый подвиг! У нас нет столько времени и ресурсов! Но это не обязательно.

Наверняка среди вашей документации есть более посещаемые разделы и менее посещаемые (а если вы не знаете, сколько посетителей читает вашу документацию, то это отличный повод настроить веб аналитику). Переработайте ваш самый посещаемый раздел. Проследите за реакцией пользователей. Сделайте выводы, внесите коррективы, возьмитесь за второй по популярности раздел. И, возможно, пожимая вам руку, новый технический директор скажет Документация? Это же очень важно! Загляну к вам в три часа, хочу узнать, как вы работаете.

Спасибо за внимание!

P.S. Хочу сказать Спасибо! моим коллегам Катерине Говердовской и Владимиру Головизнину за помощь в подготовке статьи.