Docs As Code: Документация как Код
Это раскрытие некоторых деталей по нашей недавней статье «Автоматизация обработки и анализа исходных данных» от 2023 года.
Что это такое?
Documentation as Code (Docs as Code) – это концепция разработки документации, основная идея которой заключается в разработке технической документации посредством таких же методик и инструментов, как и в процессе разработки исходного кода программного обеспечения.
Поэтому концепция Docs as Code предполагает по умолчанию использование таких типовых инструментов и сценариев как системы контроля версий (distributed version control), баг-трекеры (issue-tracking systems), процессы проверки и анализа кода (code review) и автоматизированное тестирование (test automation).
При этом ключевой особенностью является то, что непосредственно документация пишется в одном из открытых текстовых форматов (например, Markdown), после чего собирается в целевой формат посредством генератора (например, MkDocs).
Для чего это нужно?
Так как концепция Docs as Code предполагается использование тех же процессов, что и непосредственно разработка программного обеспечения, это позволяет полностью интегрировать процесс разработки технической документации в процессы разработки ПО: разработчики ПО и разработчики документации работают вместе и являются по сути собственниками (owners) документации. И это правильно.
Например, можно организовать процесс таким образом: при создании новой функции именно разработчик ПО заполняет первый черновик документации по новой функции – без этого слияние нового кода с основной веткой (git merge branch to master) будет просто заблокировано, а далее уже вступают в роль разработчики документации и ведут основной цикл формирования документации, после чего готовая документация вновь переносится на рецензирование (review) разработчику ПО. Аналогичным образом можно организовать и ведение не только проектной, но и других видов документации (например, эксплуатационной документации для конечных пользователей).
Более того, разработка документации может полноценно вестись в абсолютном любом текстовом редакторе и не требует приобретения и установки какого-либо специализированного прикладного программного обеспечения: тот же формат Markdown является открытым и достаточно простым представителем семейства LML, что позволяет создавать и редактировать документацию человеку любой квалификации и просто делает этот процесс приятным (базовый пример). При этом функциональные недостатки закрываются дополнительными плагинами, которые не требуют установки для создания документации и используются только при генерации исходной документации (расширенный пример).
Таким образом, вы фактически получаете полноценное открытое решение, которое можно интегрировать в процессы разработки ПО.
Когда это всё появилось?
На самом деле прототип современного подхода Docs As Code появился достаточно давно и использовался в крупных западных корпорациях. Автор этой статьи помнит, как более 15 лет назад лично собирал внутренними инструментами Microsoft документацию из исходного кода .NET Framework. И как эти сами средства были плохо задокументированы, и как разработчики не хотели писать комментарии в коде, поэтому приходилось самостоятельно во всём разбираться и добавлять комментарии, попутно пытаясь завести генератор.
И только спустя 10 лет, если верить информации о появлении оригинальной страницы Docs As Code на web.archive.org, данная концепция была сформулирована и допущена для широких масс. Почему так? Возможно, ситуация аналогична появлению первого в мире планшета: когда Microsoft презентовала в 2002 году Microsoft Tablet PC – народ не понял и не оценил, когда Apple показала “инновацию” iPad в 2010 году – сразу взлетело. Только в данном случае ещё Google поддержала идею на примере своей внутренней документации.
Есть ли альтернативы?
Аналогичного уровня – нет. Да, на рынке достаточно давно закрепился ряд специализированных решений для разработки документации, которые активно продвигают как профессиональные решения (например, Adobe RoboHelp, ClickHelp, MadCap Flare и проч.)… Однако их применение сегодня нецелесообразно, так как несет весьма серьезные потенциальные риски: решение должно быть надежным и проверенным, модифицируемым и расширяемым собственными силами, интегрированным в процесс разработки ПО и, главное, принадлежать владельцу документации [по личному мнению основателя ТехРайтКонсалт].
Идеальным с этой точки зрения является решение по принципу Drinking our own Champagne: вы используете собственные инструменты в разработке (например, само решение и все используемые компоненты разработаны вами же с нуля, либо задействованы компоненты Open Source). Но однозначно плохо, если в случае расширения функционала у вас полный vendor lock-in: это означает, что в лучшем случае вам можно выставить любой прайс и вы оплатите, в худшем – оставить вас без доработки в принципе. Аналогичная ситуация в случае выявления в приобретенном решении ошибок и недочетов.
Поэтому сегодня одинаково плохи: и “привычный” закрытый до 2008 года бинарный стандарт Word (.doc) Binary File Format, и разные “специализированные” закрытые проприетарные решения (от Author-it до MadCap Flare), и старые “бесплатные” открытые системы на базе принципа единого источника по типу DITA. Особо осторожными следует быть с последней: множество скрытых ограничений в бесплатной версии (от серьезных ограничений функционала до необходимости приобретения дорогостоящей IDE для комфортной работы) вкупе с устаревшим XML и высоким порогом входа – всё это в итоге дает обратный эффект от внедрения таких систем: получается слишком высокий показатель владения (TCO), что дискредитирует саму идею оптимизировать разработку технической документации.
Также важно отметить, что все эти системы не решают глобальную проблему – разработка документации всё равно остается физически отделена от процессов разработки ПО, а также остаются неразрешенными классические вопросы с тестированием и версионностью (например, в разрезе сравнения|слияния|конфликтов отдельных фрагментов документации: все же Git решает данную проблему лучшим образом, т.к. уже “натренирован” на исходном коде ПО и на различных реальных ситуациях – изобретать велосипед нет необходимости). Кроме того, невозможно будет в принципе реализовать более сложные современные сценарии (например, нашу систему непрерывного обновления в режиме реального времени).
Таким образом, система разработки технической документации – это в идеале собственная система на базе открытых и проверенных технологий (например, Markdown + Git + Python), чтобы всегда можно было легко внести коррективы в любые процессы и доработки. Либо же это как минимум отлаженный десятилетиями и самый распространенный в мире Microsoft Word и уже открытый Office Open XML (.docx) File Format. Именно по этой причине мы не предлагаем нашим клиентам “популярные” решения, в которые невозможно внести изменения собственными силами в случае возникновения проблем или потребностей в расширении текущего функционала. Всё остальное – от лукавого.
Важно отметить, что помимо Markdown, существуют также AsciiDoc и reStructuredText, которые имеют несколько больше возможностей из коробки и имеют популярные комбинации со смежными решениями (например, AsciiDoc + docToolchain или reStructuredText + Sphinx). Однако сегодня все вновь возвращаются на MarkDown и это признано лучшим результатом.
Также не следует забывать простую истину:
В основе любого решения – человеческий труд. Грамотная автоматизация – это здорово и правильно, однако даром ничего не происходит и за всё надо чем-то платить.
Всегда ли оправданы такие технологии?
Нет, не всегда. Вопреки утверждениям на тему “Зачем Word и Windows, когда есть Linux и LaTeX?”, в реальности все немного иначе. Например, если ваша цель – это концептуальная документация для высшего менеджмента, вам нужен именно Microsoft Word (потому что время и деньги, традиции и комфорт – здесь строго WYSIWYG вместо LML). Аналогично, если нужен комплект отчётной гостированной документации для сдачи по госконтракту. Но если у вас серьёзный программный продукт, который вы намерены основательно развивать, то здесь однозначно стоит рассмотреть концепцию Docs As Code.
Возможно ли большее?
Да, возможно. Например, эта статья, которую вы сейчас читаете – это не результат работы обычного генератора статических страниц: данная страница автоматически формируется и рендерится при запросе из множества md-исходников одновременно в режиме real-time, при этом всё происходит настолько быстро, что вы этого просто не замечаете. Вместе с тем, при малейшей изменении исходного кода любой страницы, все внесённые изменения будут отображены на сайте практически мгновенно (ничего нажимать и компилировать не нужно – всё полностью автоматизировано).
Продолжение следует…