Выпуск #5. Документация как код

Опубликовано 30.03.2023

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

Слушайте подкаст на любимых платформах

Поделитесь подкастом с друзьями и коллегами

---

Расшифровка выпуска

00:00 - 00:52 Приветствие

Добро пожаловать в подкаст технического коммуникатора Техкомпод!

Меня зовут Владимир Юсупов. Я - технический коммуникатор и, по совместительству, ведущий данного подкаста.

На календаре 30 марта 2023 года.

Выпуск номер пять.

В сегодняшнем выпуске речь пойдёт о популярном нынче подходе создания документации - документация как код (“docs-as-code” или “docs like code”).

00:53 - 01:57 Предпосылки

Общаясь со многими коллегами в последнее время, подметил, что всё больше российских компаний стали интересоваться подходом “документация как код” для создания и сопровождения своей технической документации.

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

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

“Документация как код” (“docs-as-code” или “docs like code”) - это подход в создании и поддержке технической документации с использованием систем, инструментов, процессов, которые применяются в разработке программного обеспечения.

01:58 - 04:50 Признаки подхода “документация как код”

Признаки подхода “документация как код” следующие:

• ведение документации в простом текстовом виде без форматирования;
• использование интегрированной среды разработки (IDE) для работы с документацией;
• использование системы контроля версий;
• использование статических генераторов сайтов;
• применение методологии разработки ПО.

Немного подробнее пройдусь по каждому из озвученных признаков.

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

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

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

Примерами здесь могут служить широко распространенные облегчённые языки разметки - Markdown, reStructuredText, Textile, Fountain и др.

Использование интегрированной среды разработки (IDE)

Вариантов оснастки огромное количество, но как правило, в качестве редактора выступает та среда разработки (IDE), которая используется смежной командой разработчиков; в основном конечно используются бесплатные варианты.

Например, Atom, Sublime Text, Visual Studio Code и др.

Использование системы контроля версий

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

Наиболее часто контроль версий реализуется с помощью Git-репозиториев.

Использование статических генераторов сайтов

Вместо систем управления содержимым (CMS) или вики-систем для публикации документации применяются генераторы статических сайтов.

Упрощённо говоря, генераторы статических сайтов - это приложения, которые компилируют исходные текстовые файлы в html-страницы.

Среди наиболее популярных генераторов - Jekyll, Hugo, Sphinx и т.д.

Применение методологии разработки ПО

В рабочих процессах написания и поддержки технической документации применяется методология разработки программного обеспечения (например, agile), а также инструменты управления командой разработчиков (например, Jira).

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

04:51 - 08:41 Информативные и понятные сообщения в коммитах

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

Итак, что же такое коммит?

Коммит - это некий снимок текущего состояния файлов в локальном репозитории. Репозиторий Git — это виртуальное хранилище проекта (или можно его представить в виде виртуального диска для хранения файлов).

Коммит выполняется командой git commit.

Для чего же нужны информативные и понятные сообщения в коммитах?

Да для того, чтобы коллеги (или даже сам автор коммита через какой-то период времени, например, через год) смогли прочитать сообщение и быстро понять какие изменения были добавлены и главное почему.

Сообщение вида обновление документа от 30 марта 2023 года вряд ли даст какую-то конкретную информацию о выполненных изменениях.

Поэтому сообщения в коммитах должны иметь определенную структуру и соответствовать неким “джентльменским” правилам.

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

Заголовок должен представлять собой краткое описание (резюме) изменения. Длина строки заголовка, как правило, составляет не более 50 символов, т.е. необходимо уложиться в данное ограничение и кратко, но понятно изложить суть изменения. Также правила хорошего тона говорят о том, что заголовок должен начинаться с заглавной буквы, быть глаголом в повелительном наклонении.

Сравните два варианта:

Заголовок сообщения git-коммита

Вариант 1	Вариант 2
Обновление документа	Обновить таблицу 4 (перечень систем-источников)

По-моему очевидно, какой вариант более конкретный и понятный.

Теперь об описании.

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

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

Например, вариант понятного описания - Обновить таблицу №4 с перечнем систем-источников в связи с интеграцией аналитической системы с новыми учетными системами...

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

Например, Задача Jira #1234.

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

Вот такая простая структура сообщения коммита значительно снизит время на его разбор в будущем.

Поэтому очень рекомендую придерживаться этих “джентльменских” правил.

08:42 - 09:25 Заключение

Спасибо, что прослушали этот небольшой выпуск от начала до конца. Если у Вас возникли вопросы, замечания или предложения, пишите мне. Заходите на мой сайт techwritex.ru. Я периодически пишу там заметки по техписьму и коммуникациям. И конечно же подписывайтесь на подкаст.

На этом у меня всё. До встречи через две недели!

С Вами был Владимир Юсупов. Подкаст технического коммуникатора Техкомпод.

Пока!