Doc as code что это

Инструменты подхода Docs-as-code

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

Интеграция инструментов разработчика с рабочими процессами

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

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

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

Если вы планируете что разработчики будут писать документацию, обязательно ознакомьтесь с презентацией Riona Macnamara на конференции Write the Docs 2015: «Документация нарушена»: как два технических писателя изменили культуру разработки Google.

Что значит “Инструменты docs-as-code”

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

• Работа в простых текстовых файлах (а не в бинарных форматах, таких как Adobe FrameMaker или Microsoft Word);
• Использование генератора статичных сайтов с открытым исходным кодом, такого как Sphinx, Jekyll или Hugo, для создания файлов локально через командную строку (вместо использования коммерческих программ, такой как FrameMaker или Word);
• Работа с файлами при помощи текстовых редакторов таких как Atom или Sublime Text (вместо того, чтобы полагаться на коммерческие инструменты с запатентованными закрытыми системами, которые функционируют как черные ящики);
• Фиксация изменений документации при помощи систем контроля версий (обычно это Git-репозиторий) аналогично хранению программного кода (вместо хранения документов в другом пространстве, например SharePoint или на общем диске); также, если необходимо, возможно хранение документов в том же хранилище, что и сам код;
• Сотрудничество с другими авторами, использующими контроль версий, например Git, для ветвления, слияния, отправки и извлечения обновлений (вместо совместной работы через большие системы управления контентом или сайты, подобные SharePoint);
• Автоматизация процесса сборки сайта с непрерывным обновлением для обновления информации на сервере при обновлении определенной ветви (вместо ручной публикации и передачи файлов из одного места в другое);
• Запуск тестов с использованием пользовательских сценариев для проверки неработающих ссылок, неправильных терминов / стилей и ошибок форматирования (вместо выборочной проверки содержимого вручную;
• Управление документами с использованием процессов, знакомых инженерам (например Scrum, Agile), например управление документацией в таск-менеджере (например, JIRA), распределение задач по спринтам раз в две недели и информирование заинтересованных сторон о готовности документации (показ демонстраций). Подробнее можно почитать в разделе Scrum и документация

В общем, docs-as-code означает использование тех же систем, рабочих процессов и подходов к работе документами, что и с программным кодом.

Преимущества подхода docs-as-code для документирования

Только потому, что можем управлять документами, как кодом, не так ли? В чем именно заключаются преимущества обработки документов как кода? Вот несколько причин для использования подхода docs-as-code.

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

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

Tip: В посте What technical writing trends will we see in 2018? находится описание того, как специализация заставляет технических писателей становиться более универсальным в работе с контентом.

Кроме того, некоторые разработчики предпочитают просто написать документ самостоятельно. Если разработчик является читателем, а другой разработчик — писателем, скорее всего, они могут найти общий язык в предположениях, предварительных знаниях и каких-то точных вещах. Короче говоря, бывает и такое, что разработчики сами пишут контент. Одного этого факта достаточно, чтобы обосновать необходимость использования подхода «docs-as-code».

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

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

При наличии технических писателей, документация по API становится совместной работой разработчиков и технических писателей. Разработчики, как правило, больше внимания уделяют написанию адресной документации, тогда как технические писатели уделяют больше внимания концептуальной документации. Независимо от разделения труда, как технические писатели, так и разработчики стремятся тесно сотрудничать друг с другом. Таким образом, инструменты docs-as-code становятся необходимыми.

Непрерывное обновление

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

Первое знакомство с правильными командами Git может занять некоторое время. Но после практики в течение нескольких недель эти команды отойдут на второй план и станут автоматическими. Устранение хлопот, связанных с публикацией и развертыванием документов, позволяет вам больше сосредоточиться на контенте, быстрее и легче выдавать обновления. Публикация и развертывание обновлений больше не отнимает время. Непрерывное обновление — это убийственная функция, которая облегчает подход docs-as-code (когда дело доходит до публикации) по сравнению с другими решениями.

Расширенное сотрудничество с другими участниками процесса

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

Работая в одном и том же хранилище, вы не раскиданы по отдельным проектам, которые существуют в разных пространствах. Инструменты Docs-as-code поощряют сотрудничество.

Гибкость и контроль

Инструменты Docs-as-code предоставляют невероятную гибкость и контроль, чтобы приспособиться к конкретной среде или инфраструктуре компании. Например, предположим, что локализованная версия нашего веб-сайта требует, чтобы мы выводили контент с определенным шаблоном URL, или мы хотим доставлять контент со специальным макетом в некоторых средах, или включать собственные метаданные для обработки файлов конкретным образом с механизмами аутентификации или whitelisting вашей компании. С помощью инструментов docs-as-code файлы открываются и настраиваются в соответствии с желаемой логикой. Эти открытость и гибкость могут быть особенно важны, при интеграции документов на веб-сайт, а не генерируете отдельный вывод (см. Шаблон 2: одностраничный веб-сайт).

Инструменты docs-as-code прямо пропорциональны вашим знаниям в кодировании. На базовом уровне почти все инструменты docs-as-code используют HTML, CSS и JavaScript. Так что, если вы мастер в этих веб-технологиях, то нет ничего невозможного.

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

Tip: Подробнее о переходе к инструментам docs-as-code см. В разделе Кейс для изучения: Переход на Docs-as-code

Не только инструменты, но и процесс

Исторически дискуссии о docs-as-code были сосредоточены на инструментах, а не на процессах. Но, кажется, можно найти хороший повод для расширения определения docs-as-code и включить реализацию инженерных процессов управления документами. Безусловно, наиболее распространенный подход к разработке программного обеспечения — Agile scrum. О нем подробнее в разделе Scrum и документация

Более сложные факторы

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

• локализация;
• повторное использование контента;
• версионирование;
• аутентификация;
• PDF.

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

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

Jekyll предоставляет язык шаблонов под названием Liquid, который позволяет выполнять условную фильтрацию, повторное использование контента, переменные и т. Д., Что соответствует требованиям выше. Автор использовал эту продвинутую логику, чтобы получить исходный код без дублирования содержимого. Другие генераторы статичных сайтов (такие как Hugo или Sphinx) имеют похожую логику шаблонов и сценариев, которая позволяет выполнять сложные задачи.

Для того, чтобы справиться с PDF при помощи Jekyll, был интегрирован инструмент под названием Prince, который преобразует список HTML-страниц в документ PDF, в комплекте с текущими верхними и нижними колонтитулами, нумерацией страниц и другими стилями печати (в нем даже используется CSS для стиля). также можно использовать Pandoc, чтобы выполнять более простые требования PDF. Обработка PDF возможна, но обычно такая функция не является коробочной (кроме Sphinx).

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

Заключение

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

Docs as Code: Пишем тексты как код

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

Средний уровень
Сертификат Stepik

35 учащихся

Чему вы научитесь

• пользоваться языком текстовой разметки Asciidoc и PlantUml для создания исходников технической документации;
• собирать техническую документацию локально в формате html;
• настраивать автоматическую сборку и размещение технической документации в сети интернет

О курсе

Цель курса состоит в знакомстве с подходом Docs as Code при написании текстов.

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

Особенность курса состоит в создании структуры технической документации и написании файлов с исходниками текстов из кейса через консоль с помощью редактора vim или аналогов. Это необходимо для лучшего понимания используемых технологий. Только после завершения этого этапа рекомендуется переходить к использованию специализированных IDE (например, IntelliJ IDEA), позволяющих значительно ускорить процесс работы над текстами.

В курсе будут использованы технологии:

Для кого этот курс

Технические писатели, системные аналитики, разработчики. Все, кто пишет тексты и связан с ИТ

Начальные требования

• опыт работы с *nix системами;
• базовые знания bash;
• понимание технологии git;
• знания английского, достаточные для чтения технической литературы

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

© , ТехРайтКонсалт | Разработка технической документации для вашего программного обеспечения | Обратиться за помощью ➡

Автоматизация процесса создания технической документации на основе подхода Docs as Code

Бармина Анастасия Александровна – специалист по разработке технической документации АО «ЦКР».

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

Ключевые слова: автоматизация, нормативная документация, DevOps, Docs as Code.

Под подходом «документ как код» (англ. Docs as Code) подразумевается практика обработки документации таким же образом, как и разработка кода. Документация может быть разнообразной: от веб-справок до автоматически сгенерированных документов по API и контекстно-зависимой справки.

Docs as Code использует два основных принципа.

1. Использование одинаковых средств с командой разработки DevOps: это включает в себя контроль версий и автоматизированное развертывание.
2. Использование тех же моделей жизненного цикла программного обеспечения (ПО), что и при разработке кода [1].

Это не означает, что технический писатель должен делать все точно так же, как команда разработчиков, но в целом необходимо достигнуть целостности и скоордированности процессов разработки и создания документации. Например, специалист по документации может выбрать генератор статических сайтов, предназначенный для создания документов, но по-прежнему держать документы под контролем версий, добавлять процесс сборки и выпуска документов в те же конвейеры развертывания, что и код, и т. д [2].

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

Как и в любом подходе, Docs as Code имеет свои плюсы и минусы. Некоторые из них носят ситуативный характер. К достоинствам можно отнести: повторное использование как программного обеспечения, так и человеческих ресурсов; тесный контакт с разработчиками; автоматизация процесса документирования.

К недостаткам подхода можно отнести: повышение порога технических навыков для специалистов. Существует большое количество инструментов, доступных для Docs as Code. Для всех них требуется определенный порог вхождения.

Для построения стандартного набора документации (руководство администратора, руководство пользователя и wiki-справка) необходимо использование:

1. Упрощенного языка разметки Markdown или AsciiDoc.
2. Системы контроля версий (часто, но не всегда, это git) в сочетании с удаленным хостом контроля версий, таким как GitHub или GitLab.
3. Шаблоны документов, выполненные в редакторах Microsoft Office Word, LibreOffice Writer или TeX.
4. Генератора статических сайтов для создания документации.
5. Средства автоматизированного развертывания документации.

На приведенной ниже диаграмме показан рабочий процесс создания документации, в котором используется подход Docs as Code (рис.1).

Рисунок 1. Процесс создания документации с использованием Docs as Code.

Последовательность действий следующая:

1. Технический писатель создает локальную ветку для своих изменений документации.
2. Специалист публикует ветку в системе контроля версий.
3. Автор создает pull request.
4. После уведомления о поступившем pull request документация проверяется ответственными лицами и принимается решение одобрить или отклонить изменения.
5. После pull автоматический конвейер выполняет различные проверки документации.
6. В случае, если pull request одобрен, содержимое можно объединять с основной веткой.
7. Далее, документация доставляется по различным источникам – это может быть формирование документа в различных форматах или обновление страниц wiki.

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

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

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

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

Весь цикл разработки документации по методологии Docs as Code может быть построен с использованием бесплатного программного обеспечения.

Для проведения вычислительного эксперимента по оценке эффективности подхода Docs as Code были взяты схемы описания процесса создания документов с использованием Docs as Code и Microsoft Office Word (как представитель текстовых редакторов) [3].

В качестве документа создавалось руководство системного программиста, выполняемое в соответствии с ГОСТ 19.503. Для расчета функционально ориентированных метрик документа исходный набор информации взяты характеристики [4]. Для оценки эффективности подходов использовалась методика, описанная в [4, 5], и проведен вычислительный эксперимент. Для наглядного сравнения результатов вычислительного эксперимента результаты обобщены в соответствии с рис. 2.

Рисунок 2. Результат проведенного эксперимента.

В результате вычислительного эксперимента подход Docs as Code оказался эффективнее в применении, чем использование текстового редактора на примере Microsoft Office Word. Подход Docs as Code снижает сложность процесса создания документации в среднем на 35%. Таким образом, использование Docs as Code для создания различного вида технической документации является необходимым в применении техническими писателями, поскольку сокращает время разработки и доставки документации до конечного пользователя, однако, стоит понимать, что данный подход имеет место быть среди технических писателей, у которых имеется определенный уровень подготовки.

1. Docs-as-code: DevOps-технологии в документировании, или как подружить технического писателя и разработчика: сайт. – URL: https://habr.com/ru/company/zyfra/blog/578486/ (дата обращения: 16.01.2023).
2. Docs as Code: how does it improve Developer Experience?: сайт. – URL: https://blog.mia-platform.eu/en/docs-as-code-how-does-it-improve-developer-experience (дата обращения: 16.02.2023).
3. Ozerova, M. I. Comparison of Document Generation Algorithms Using the Docs-as-Code Approach and Using a Text Editor / M. I. Ozerova, I. E. Zhigalov, V. V. Vershinin // Advances in Intelligent Systems and Computing. – 2020. – Vol. 1294. – P. 315-326.
4. Albrecht, A.J.: Measuring application, development productivity. In: Share/Guide Application Development Symposium, pp. 83–92 (1979).
5. Docs as Code: сайт. – URL: https://www.writethedocs.org/guide/docs-as-code (дата обращения: 16.02.2023).