Doc as code что это

(6) Техническая документация в IT-проектах. Docs-as-code на примере инструмента Foliant

Открытый онлайн-курс о технической документации в IT-проектах.

Лекция 6. Как создать инфраструктуру документирования как кода на примере инструмента Foliant (Константин Валеев, руководитель отдела аналитики и документации в Ростелеком ИТ)

documentat.io

May 15, 2020

More Decks by documentat.io

(9) Локализация документации
documentatio
(8) Для чего нужны Help Authoring Tools на примере MadCap Flare
documentatio
(7) Техническая документация в IT-проектах. ГОСТ 19 в современной разработке
documentatio
(4) Техническая документация в IT-проектах. Требования к документационному инструментарию
documentatio
(#3) Техническая документация в IT-проектах. Жизненные циклы технических документов
documentatio
(#2) Техническая документация в IT-проектах. Типичные проблемы с документацией
documentatio
(#1) Техническая документация в IT-проектах. Определение технической документации.
documentatio

Other Decks in Education

Library Prefects 2023-2024
cbtlibrary
TP3_-_Réplication.pdf
bernhardsvt
Ch1_-_Partie_1.pdf
bernhardsvt
KnockLearnサービス説明資料

knocklearn

summary of CEO factory
Ch1_-_Partie_2.pdf
bernhardsvt
Earthquake and Disaster Prevention Information for UTokyo International Students
utokyoissr2360
英語ができなかった自分達が、グローバルチーム立ち上げに挑戦！？
2023年度秋学期 統計学 講義の進め方と成績評価について (2023. 9. 26)
akiraasano

When Meteor-Grade AI Comes Knocking, Do We Still Need to Learn AWS? �� A Traveler’s Perspective on a Decade of Decomposition and Integration (AWS Community Day Taiwan 2023)

Human Perception and Cognition — Lecture 4 — Human-Computer Interaction (1023841ANR)
Oracle Database入門 — データベース構築編
oracle4engineer

Featured

Rebuilding a faster, lazier Slack
samanthasiow
Designing for humans not robots
Producing Creativity
orderedlist
RailsConf 2023
tenderlove
How to name files
Keith and Marios Guide to Fast Websites
Raft: Consensus for Rubyists
Faster Mobile Websites
Optimizing for Happiness
[RailsConf 2023 Opening Keynote] The Magic of Rails
eileencodes
Java REST API Framework Comparison — PWX 2021
The Pragmatic Product Professional
lauravandoore

Transcript

Документация как код
на примере Foliant
Константин Валеев, май 2020

Привет!
• Руковожу отделом аналитиков и техписателей в «Ростелеком
ИТ» — софтверной дочке «Ростелекома».
• Разрабатываем свой инструмент ведения документации —
Foliant.

О чём поговорим
1. Кратко обсудим Docs as Code: что это, когда полезен, какие
есть ограничения.
2. Посмотрим как этот подход можно реализовать.
3. Немного взглянем на то, что умеет Foliant.

Docs-as-Code

Docs-as-Code
1. Ведение документации в текстом формате — человекочитаемой
разметке.
2. Использование инструментов и подходов разработки кода.
3. Плюсы: не нужна отдельная инфраструктура; легко поднимается;
понятно и нативно для команды разработки; все плюшки
инструментов для работы с кодом.
4. Минусы: сложнее в использовании, не разработчикам придётся
привыкнуть, необходимо соблюдать правила работы с инструментами,
нужно развернуть и поддерживать.

Процесс работы над документацией
Над документацией работают так же, как над кодом:
1. Исходные тексты документации в человекочитаемой
разметке.
2. Хранятся в системе контроля версий (git).
3. Релиз через Continues Integration: на веб-сайт, в PDF и
Word.

Используем инфраструктуру разработки
1. Текст кода ➝ Текст документа
2. VCS для кода ➝ VCS для документации
3. MR для код-ревью ➝ MR для ревью документации
4. CI для сборки кода ➝ CI для сборки документации
5. Code Style и релизные политики ➝ Styleguide и соглашения
6. Автотесты сборки ➝ Автотесты документации

Source Code ➝ Source Docs
• Markdown
• RestructuredText
• Asciidoc
Системы контроля версий
https:/
/www.youtube.com/
watch?v=5N3zyvXB6Jg

Code Review ➝ Doc Review
Мердж-реквесты для согласования документации: читают не
только разаработчики (маркдаун легко читается и в
исходнике), связь с тикетами в джире.

DevOps ➝ DocOps
© Thomas Pryce

Автотесты
• Линтинг разметки и орфографии при сборке
• Валидность ссылок
• Соответствие глоссарию
• Стоп-слова
• Что угодно

Переиспользования при сборке
• Вставка других текстов
• Вставка сниппетов кода
• Генерация диаграмм
• И даже исполнение кода

Сборка: PDF и Word (Pandoc)
Сборка: Сайт (MkDocs)
Сборка: Сайт (Slate)
Сборка: Google Docs (Pandoc/pyDrive)
Сборка: Confluence
Foliant
• Markdown-based
• Клей между хорошими инструментами
• Модульность и расширяемость
• Unix-way

Как пользуемся
• Пишем в маркдауне
• Несколько проектов
• Центральный проект для сборки
• Мердж-реквесты и вычитка
• Gitflow и Trunk-based
• CI/CD

Docs as code

Техническая документация нужна, техническая документация важна. С этим согласится каждый.

Но вот в вопросе где и как ее писать единого мнения нет.

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

Почему разработчики не пишут ее?

— Не удобно писать

Чтобы разработчикам было удобно писать документацию можно использовать уже знакомые и удобные инструменты.

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

— Документация пишется не в специализированном формате не в проприетарном ПО, которому нужно долго обучаться, а на легком языке разметки (например, Markdown).

— Документация хранится в репозитории Git.

— Документация собирается в нужный формат при помощи генератора статических сайтов (Sphinx, Hugo, Jekyll, MkDocs). Форматов может быть сразу много: HTML, PDF, DOCX и так далее. Или может не собираться вовсе, а читаться прямо в репозитории, ведь все репо поддерживают рендер разметки.

— Документация пишется и обновляется коллаборативно.

Такой подход дает кучу плюсов:

— Поддерживается версионность документации 1 к 1 как версионность кода.

— Удобно проводить ревью изменений, сразу видно что изменилось

— Легко поднять историю изменения документации

— Документацию можно пушить вместе с изменениями в коде. То документация всегда будет актуальна. Если доброску откатят, то и документация откатится тоже.

— С языками разметки типо Markdown знакомо огромное число людей, а изучить с 0 занимает очень мало времени. При этом языки разметки предоставляют минимум инструментов позволяющий сделать удобную документацию и при этом не перегрузить ее форматированием.

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

— Документация не привязана к конкретному инструменту. Если хочется можно через обычный текстовый редактор открыть, или использовать специализированные приложения типо Obsidian.

— Функциональность документации езгранично расширяема и позволяет создать настолько мощную (или, наоборот, простую и дешевую) систему, насколько нужно именно вам

— Использование GIT позволяет реализовать инструменты непрерывного развертывания для документации. Можно и не использовать, а смотреть документацию прямо в git.

Docs as code — используйте инструменты разработки для технической документации!

Docs-as-code: DevOps-технологии в документировании, или Как подружить технического писателя и разработчика

Привет, Хабр! Меня зовут Роман Блинов, я ведущий технический писатель в «Цифре» — в команде по развитию платформы ZIIoT. Этот пост будет о подходе Docs-as-code для документирования разработки ПО. Пишу с прицелом на тех читателей (то есть писателей), кто этот подход пока не пробовал и по факту имеет набор файлов в Confluence, файлы формата .docx и .pdf, на поддержку, обновление и оформление которых тратится порядка 70 % времени (а хотелось бы меньше), и 101 отговорку разработчиков, чтобы не участвовать в документировании.

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

На что жалуетесь? Три боли технического писателя до внедрения Docs-as-code

1. Разработчики слабо вовлечены в процесс документирования

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

2. Команда документирования слабо информирована о ходе разработки

Когда система документирования встроена по формату Docs As Service, группа документирования оторвана от групп разработки и формирует документацию на основе постановок, поступающих от разработчиков. При этом группа документирования не имеет представления о ходе разработки и тех процессах, которые протекают в ее рамках. Более того, ответственные за документацию практически не владеют информацией о развитии продукта и не могут полностью отвечать за консистентность документации и ее актуальность, так как всегда есть человеческий фактор, когда кто-то кому-то банально забыл сказать, что вышел новый релиз или что-то поменялось в текущем. Документация в этом случае превращается в набор файлов в Confluence и других форматах, например, .docx и .pdf, которые постоянно приходится поддерживать, обновлять и вообще держать в адекватном состоянии.

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

3. Нет версионности

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

Чем лечить будем

Чтобы избавиться от ненужных стрессов, требуется изменить образ жизни технического писателя, точнее подход к документированию. В качестве панацеи в писательской среде уже давно обсуждается и применяется система организации документирования Docs As Part Of Development Team, когда технические писатели включены в процесс разработки и подготовка документов является его неотъемлемой частью. Документация ведется в формате Docs-as-code, основанном на технологиях DevOps в разработке ПО, когда работа над документацией строится на тех же принципах, что и работа над исходным кодом, и передается заказчику в рамках аналогичных процессов.

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

В чем суть и преимущества этого подхода

В основе подхода лежит переиспользование инфраструктуры разработки ПО для ведения документации.

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

Особенности:

· Ведение документации в простом текстовом формате.

· Использование инструментария и подходов к разработке исходного кода.

Плюсы: не нужно строить отдельную инфраструктуру (она и так уже есть), легко поднимается, понятна для команды разработки.

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

Структура разработки документации

Работа над документацией в рамках подхода Docs-as-code включает следующие элементы, повторяющие аналогичные шаги разработки:

1. Текст кода — Текст документа.

2. Система контроля версий кода — Система контроля версий документа.

3. Merge Request для код-ревью — Merge Request для вычитки документации.

4. CI для сборки кода — CI для сборки документа.

5. Code Style и релизные практики — Руководства по стилю и редакционные политики.

6. Автотесты для сборки — Автотесты для документации.

Рассмотрим каждый элемент по порядку.

Текст кода — Текст документа

В основе подхода Docs-as-code лежит легковесная разметка и простой текст. Нами был выбран язык разметки Markdown, т. к. он наиболее прост в освоении и практичен в применении. Можно сказать, что Markdown является стандартом при разработке подобной документации. Также можно применять ASCIIDoc или reStructured Text, но данные языки обладают достаточно большим набором правил, которые необходимо освоить, а также требуют специфического программного обеспечения.

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

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

Для работы с текстами доступны все расширенные текстовые редакторы. В нашем случае мы применяем редактор VS Code, так как он хорошо встраивается в наш процесс интеграции и доставки обновлений, но можно использовать и другие — Atom и т. п. Кстати, один из редакторов — Typora — позволяет очень легко и быстро преобразовывать текст из двоичных форматов типа .docx в Markdown. И его использование в комбинации с VS Code помогает сильно ускорить процесс переработки документов из других форматов.

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

Система контроля версий кода — Система контроля версий документа

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

Такой подход несколько отличается от совместного редактирования документации с использованием Sharepoint и других ресурсов. С одной стороны, скорость такой совместной работы может немного упасть, так как необходимо создавать свою версию файла, а затем осуществлять процесс слияния. То есть не получится быстро взять и набросать какой-то текст. Зато мы получаем процедуру вычитки документации — в процессе Merge Request мы можем контролировать все изменения, отклонять те, что не соответствуют, и не пускать их в основную ветку. Также мы можем увидеть буквально по каждой строке, кто и когда ее создал и изменил. Таким образом, кроме отслеживания изменений глобально по репозиторию мы можем отслеживать их в отдельных файлах.

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

Merge Request для код-ревью — Merge Request для вычитки документации

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

CI для сборки кода — CI для сборки документа

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

При подходе Docs-as-сode документация хранится непосредственно в репозитории с исходным кодом проекта, читаема, как и все материалы в Git, и передается заинтересованному лицу вместе с исходным кодом проекта. Все материалы при таком подходе соответствуют той версии ПО, которая передается заказчику, и автоматически являются актуальными, что значительно снижает временные затраты на актуализацию документов.

В случае же, когда заказчику по каким-либо причинам требуется документация в отчуждаемом формате — .docx, .pdf и т. д., наш подход позволяет сгенерировать необходимый документ с использованием утилиты под названием Pandoc. Данный инструмент позволяет выполнять конвертацию документов из Markdown и обратно в большинство используемых форматов. На выходе мы можем создать практически любой файл и передать его либо разместить в системе управления документацией, которой пользуется заказчик.

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

Code style и релизные практики — Руководства по стилю и редакционные политики

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

Автотесты для сборки — Автотесты для документации

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

· линтинг разметки и орфографии;

Отдельные вопросы локализации документации

Для локализации документов у нас применяется открытое ПО Weblate, которое интегрируется с Git и позволяет выполнять локализацию как обычных текстовых файлов, так и json-файлов и др. Важно, что данное ПО работает по системе «память перевода» и позволяет автоматизировать и ускорить процесс перевода за счет накопления базы готовых сегментов текста, которые потом программными средствами вставляются в текст. Это весьма актуально для технических текстов, где содержится большой объем повторяющихся блоков и наименований.

Ну и не без ложечки дегтя

«Классно!» — скажете вы и будете бесконечно правы. Удобный модный формат с автоматизацией большинства функций обработки текста, быстрый процесс передачи и доставки заказчику, версионность — что может быть лучше?! Мы уже победили. Надо только все корректно оформить.

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

Да, все классно: быстро, удобно и легко. Но Docs-as-code — это не просто система документации, это нечто более близкое к философии, которая требует в первую очередь строгой внутренней дисциплины, выстроенных бизнес-процессов и, главное, желания улучшить жизнь самим себе. А для этого требуется, как сейчас модно говорить, выйти из зоны комфорта и встать на путь постоянного развития.

С одной стороны, техническому писателю удобно работать по старой системе: сидишь себе спокойно, правишь рисунки в тексте — и время идет, рабочее, между прочим, и зарплата капает. А тут брось все это, изучи что-то новое, да еще освободи 70 % своего рабочего времени. И чем потом это время занимать? Конечно, работой над качеством документации, а это сложнее. С другой стороны, есть разработчик, он всегда занят, у него тысяча задач. Когда ему заниматься рисованием схем и объяснением писателю, а что же, собственно, его сервис делает и как. Конечно, времени нет. А еще есть руководитель проекта, которому в рамках нового подхода придется придумывать, как и когда встроить документирование в процесс работы.

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

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

• docops
• технический писатель
• документация
• документирование
• блог компании цифра
• docsascode

• Блог компании Цифра
• Управление разработкой
• Подготовка технической документации

Doc as code что это

DocFactor’2017

Конференция о технической документации. Для техписателей и не только.

26 ноября 2017, Новосибирск, Академгородок.

Документация как код в промышленных масштабах
Николай Волынкин, Plesk, Технический писатель

История о том, как мы в Plesk внедряем лучшие практики разработки ПО в разработку документации.

— Какие проблемы были в разработке документации и как мы их решаем.
— Что такое разработка документации как кода («docs like code»): легковесные языки разметки, контроль версий, непрерывная интеграция и поставка (CI/CD), контролируемая публикация, связь с разработкой и выпуском продукта.
— В чём польза для технических писателей и для бизнеса.
— Как перейти на docs like code, не ломая процессы и не выкидывая легаси.

Доклад адресован всем, кто заинтересован в управлении знаниями в компании: техписателям и их руководителям, менеджерам продуктов и проектов, тимлидам и архитекторам, CTO, энтузиастам свободного программного обеспечения.

Технологии и ключевые слова: reStructuredText, Sphinx, Markdown, Jekyll, Git, CI/CD, GitLab CI, Docker, pandoc.