Вот и обещанная вторая статья по Docs as code. В части 1 я рассказала про основные подходы создания технической документации. В этой статье я не буду останавливаться на других подходах, вас ждет чистый Docs as code.
Как мы знаем, подход Docs as code основан на принципах и инструментах разработки, поэтому сегодня я расскажу о фундаментальных концепциях разработки, на которых строится понимание подхода Docs as code в моей голове. Выяснив это, все инструменты подхода начинают склоняться к вашим ногам. Погнали!
Когда Docs as code необходим
Я уже поверхностно задела типичные задачи, которые лучше решать через этот подход. Но давайте конкретнее. Когда же необходим Docs as code?
Я бы включила в аспект «необходимо» следующее:
Снижение нагрузки на команду разработки при создании портала документации.
Абсолютный контроль над ресурсами документации.
Быстрый и надёжный аудит изменений.
Автоматизированная проверка качества и согласованности документации.
Полная автоматизация генерации документации из кода.
Разберем, что включает в себя каждая задача, и почему Docs as code необходим для ее решения.
Снижение нагрузки на команду разработки при создании портала документации
Бизнес-проблема
Именно отдел разработки создает и доставляет запрошенную бизнесом функциональность. Отвлечение разработчиков на задачи, которые напрямую не связаны с продуктом, замедляет выпуск новых фич. К сожалению, до сих пор создание и поддержка портала документации относятся именно к непрямым задачам. При этом бизнес не всегда готов покрывать расходы на подписки или лицензии стороннего ПО для документации (напомню: это непрямая для разработки задача), или же ему нужен более гибкий и настраиваемый инструмент.
Docs as code решает
Технический писатель как самый релевантный и близкий документации специалист, который владеет навыками и инструментами подхода Docs as Code, может самостоятельно создать и поддерживать полноценный портал документации. Для этого не нужен бэкенд, база данных или серверные приложения.
Абсолютный контроль над ресурсами документации
Бизнес-проблема
Компании, которые пользуются сторонним ПО (особенно распространяемым по подписке или лицензии), в некотором смысле зависят от этого ПО. Ведь они могут внезапно изменить свои условия, поднять цены или исчезнуть. Это ставит под угрозу всю интеллектуальную собственность компании. Напомню, что многие программные продукты, например, Confluence, больше не распространяются как on-premise решение. Миграция с одного стороннего ПО на другое стороннее ПО стоит дорого.
Docs as code решает
За счет использования open-source инструментов, а также возможности их развернуть где удобно для компании, Docs as code обеспечивает абсолютный контроль над документацией. Компания может навесить на репозитории документации все то же самое, что навешено на репозитории разработки: разграничение прав доступа, доступность из-под контура компании, создание резервных копий, создание кронов и другое.
Быстрый и надёжный аудит изменений
Бизнес-проблема
История изменений важна в сфере разработки. Это помогает разобраться в возникших инцидентах и понять, какой кусок кода был тому причиной. В корпоративных инструментах документации (Confluence, SharePoint и других) история изменений есть, но ее отправной точкой считается сохранение целой страницы определенным пользователем. Комментарии привязаны к странице. Нет функции решения конфликтов контента при изменении страницы несколькими пользователями одновременно. И нет привязки изменений к конкретной задаче. Поэтому качественно восстановить хронологию событий становится сложно.
Docs as code решает
Система контроля версий является незаменимым инструментом в разработке, который ведет историю всех изменений. Например, в системе Git каждый коммит несет в себе изменения с указанием автора, даты и комментария для каждой строки. А функциональность MR’ов и PR’ов в GitLab и GitHub соответственно расширяет базу изменений, давая возможность выполнить ревью внесенных изменений, не затрагивая другие файлы репозитория, а также выполнить слияние изменений с веткой main/master только после одобрения правок всеми ответственными лицами.
Автоматизированная проверка качества и согласованности документации
Бизнес-проблема
В компании даже с несколькими десятками документов сложно следить за стилем, терминологией и повторениями, допущенными в разных документах. Назначать ответственных за соблюдение правил документации из специалистов не документации звучит как дорогостоящее предприятие. Еще более дорогостоящее, когда инструменты, в которых создаются документы, не имеют функциональности следить за выполнением этих правил.
Docs as code решает
Использование уже реализованных линтеров, написание скриптов и автоматические тесты для документации, как и для кода, существуют именно в подходе Docs as code. Если сильно постараться, можно «зашить» проверку правил стайлгайда во все репозитории с документацией. Это тоже нетривиальная задача, но лежать в этом направлении можно и нужно. Выполнять глобальный поиск, поиск по регулярным выражениям, такую же глобальную и по регулярным выражениям замену символов можно прямо из IDE. Такие проверки, наряду с запуском сборки, являются частью CI/CD, что не дает опубликовать заведомо ошибочные изменения.
Полная автоматизация генерации документации из кода
Бизнес-проблема
Такие продукты компании, как API, SDK, CLI часто дублируются в документации. Первое, что подлежит копированию, это схема самих методов и команд. Расхождение только описания можно назвать приемлемым. Но если устаревает сразу все, а схема методов и команд — это ключевое «все», это катастрофа. Копирование вручную будет помогать этому процессу.
Docs as code решает
Использование близких к коду инструментов и технологий позволяет сократить дублирование к минимуму:
Спецификация OpenAPI служит источником для генерации серверного и клиентского кода, а также самой документации. Эту бесценную технологию интегрируют все больше и больше инструментов, включая SSG из подхода Docs as code.
Генераторы SDK документации (Doxygen, JSDoc и другие) позволяют генерировать документацию из аннотаций в самом коде.
Библиотеки для разработки и документирования CLI (click, commander.js и другие) позволяют генерировать документацию из аннотаций в самом коде. Существуют библиотеки, которые работают по типу спецификации OpenAPI.
Три кита Docs as code
Подход Docs as code сформулирован для процессов создания технической документации по подобию процессов разработки. А техническую документацию в свою очередь пишут технические писатели, к которым часто не предъявляется требование в научной степени компьютерных наук. Часто спрашивается филологическое образование. И это нормально.
Но что, если я скажу, что инструменты для Docs as code написаны разработчиками для среды разработки? Вы явно это заметили, когда решили попробовать запустить несколько страниц на хоть каком SSG. И это в корне меняет то, как стоит понимать этот подход и использовать его.
Фраза «разработчики для среды разработки» дает понять, что эти инструменты следуют заветным правилам программирования. И сейчас я расскажу о базовых понятиях, которые нужны для понимания подхода Docs as code.
Как вы поняли из заголовка, таких понятий три:
Абстракция.
Синтаксис.
Конфигурация.
Рассмотрим каждый из них подробнее, как и их связь.
Абстракция
«Абстракция — это представление окружающей нас действительности в упрощенном виде.��
Вы точно замечали, что в приложениях не всегда есть то, что нам нужно. Иногда это целая функция, а иногда это отсутствие поля для отчества. Это все связано с основным моментом в разработке: реализуется только абстракция, которая важна для конкретного бизнеса конкретно сейчас, а это не весь спектр действительности.
Что может включать абстракция? Чаще внимание с абстракции смещается на понятие «объект» как реализации этой абстракции. У объекта есть:
Атрибуты, или признаки.
Состояние.
Поведение.
Самым идеальным примером перечисленного является GameDev, где у нас есть игровые механики, персонажи, уровни.
Синтаксис
«Синтаксис — это попытка формализовать абстракцию.»
Синтаксис, грубо говоря, — это способ записи. Синтаксис есть у форматов данных, языков разметки, языков программирования.
Я не буду углубляться в то, по каким правилам составляется синтаксис языков программирования, но расскажу об общих составляющих синтаксиса.
Лексика
Базовые «кирпичики», на которых строится синтаксис. Основные лексические элементы:
Ключевые (зарезервированные) слова. Имеют специальное значение в рамках лексики. Пример: теги HTML.
Идентификаторы. Имена, которые задаются для оперирования некоторыми данными. Пример: переменная с названием продукта для всей документации.
Разделители. Знаки, которые разделяют части. Пример: пустая строка.
Структура
Правила объединения лексических элементов в осмысленные конструкции. Включает:
Выражения. Комбинации операндов и операторов, которые выполняют определенную функцию. Пример: обозначение второго уровня заголовка через символы «## ».
Инструкции. Неразделяемые исполняемые единицы. Пример: запись значения через символ «:».
Определения. Правила для создания крупных исполняемых единиц. Пример: отделение метаданных от контента страницы.
Комментарии. Текст, который игнорируется движком, и используется для пояснений.
Конфигурация
«Конфигурация — это одна из реализаций абстракции.»
Конфигурация — это набор параметров и настроек, которые определяют поведение и функционирование программы, системы или компонента. В случае с Docs as code у каждого инструмента есть конфигурация: у SSG, у генератора документации и другого. Существование конфигураций позволяет изменять поведение приложения без необходимости менять его код.
Конфигурации классифицируются по разным признакам. Нас будут интересовать только два из них.
Источник конфигурации
Место, где хранятся данные конфигурации. Распространенные источники:
Файлы. Текстовые файлы с расширением .ini, .json, .yaml, .xml или .env часто указывают на конфигурацию.
Переменные окружения. В приложениях записываются в файле .env. Такие настройки хранятся в переменных операционной системы.
Конфигурация по окружениям
Каждое окружение имеет разный набор настроек для упрощения ведения жизненного цикла ПО:
Разработка (dev).
Тестирование (stage/sandbox).
Продакшн (prod).
Взаимосвязь китов
Эти понятия связаны как протоны и электроны атома. Вышибая одну частицу, мы либо меняем вещество, либо уничтожаем его.
Синтаксис и конфигурация не могут жить друг без друга, ведь конфигурация записывается по правилам синтаксиса.
Если посмотреть на большинство инструментов подхода Docs as code, а именно: GitLab, GitHub, IDE, SSG, генераторы документации, языки разметки (Markdown, AsciiDic, restructuredText, HTML и другие), OpenAPI, плагины, пакеты, библиотеки и другие. Все они базируются на этих трех китах и без них не существуют.
Заключение
Возможно такой ход размышлений не всем подходит, но мне он показался очень логичным для объяснения подхода Docs as code.
И вот осталась последняя статья этого цикла. В ней я предложу шаблоны по использованию инструментов подхода Docs as code. Она пока в разработке, поэтому: to be continued...
