Документация как код (Docs as Code)

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

Docs as Code представляет собой подход к разработке программной документации с использованием тех же инструментов, что и для написания кода. Как это происходит? Разработка документа осуществляется при помощи упрощенного языка разметки (Markdown, reStructuredText, Asciidoc). Для хранения документации используются репозитории Git (GitHub и GitLab), что позволяет отслеживать изменения и контролировать версии. Сбор документации в различные форматы происходит при помощи генераторов статических сайтов.

Данный подход отличает ряд преимуществ:

• заинтересованность разработчика в процессе подготовки документа;

• версионность;

• высокая скорость загрузки сайта;

• простота публикации;

• доступность.

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

Хранение документов в репозиториях Git позволяет непрерывно обновлять в них информацию. Изменения в документах отображаются за долю секунды. Представим, что мы для внесения коррективов пересылаем документ в формате DOCX. Сколько бы это заняло времени? Значительно дольше. К тому же, контроль над изменениями в таком случае не автоматизирован. Доверять придется исключительно внимательности участников процесса разработки документации.

Многостраничный файл в формате PDF может загружаться несколько минут, что довольно долго относительно сайтов с подходом Docs as Code. Страницы сайтов открываются мгновенно, что ускоряет время подготовки программного документа в целом.

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

Бесспорным плюсом Docs as Code является его доступность. Процесс разработки и размещения документации в целом бесплатный. Потратиться придется только на расширение возможностей в GitHub или GitLab (увеличение объема для хранения и обеспечение защиты информации).

К недостаткам рассматриваемого подхода относятся:

• необходимость настройки системы;

• отсутствие технической поддержки;

• высокие требования к навыкам технического писателя;

• сложность работы с языками разметки.

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

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

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

Подход Docs as Code позволит ускорить и упростить процесс разработки программной документации. Обучив технических писателей работе с Git и специфике различных языков разметки, можно сократить до минимума трудоемкость их работы.