Использование ASCIIDoc для управления документацией на проекте (Часть 1)

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

Здесь мы с моим коллегой Алексеем Васильевым (@ayuvasiliev) расскажем о том, как упростить команде жизнь, используя подход Everything-as-Code. И о том, как этот подход нам позволил сократить время подготовки и повысить качество необходимых документов.

С чего начинаем

Как, наверное, в большинстве компаний, ситуация с документацией на старте — не самая радужная. Поскольку:

• для написания всей документации де-факто используется MS Word;

• обмен файлами идет через e-mail;

• даже если данные хранятся где-то, они — в бинарном формате;

• очень сложно отслеживать изменения, особенно если они не внесены в лист изменений;

• даже если документация хранится в корпоративной вики  (например, Confluence), она хранится отдельно от кода проекта или приложения.

Что хотим получить

Для нас самым важным при работе с документацией является:

• единая информационная среда (общая база знаний, прозрачный доступ к коду, управление проектами) для всех ролей внутри кросс-функциональной команды (SA/BA/Dev/QA/Eng/Support);

• единая точка входа для взаимодействия со всеми внешними компаниями и заказчиками;

• прозрачный, простой и удобный интерфейс для работы;

• автоматизация процессов сборки конечных версий;

• использование различных шаблонов.

Everything As a Code

Концепция Everything As a Code, в частности Docs As a Code, — использование тех же инструментов, что и при разработке ПО.

Everything As a Code (Все Как Код) — это практика обращения со всеми частями системы как с кодом. Данный подход позволяет хранить конфигурации, документы и все остальное вместе с исходным кодом в репозитории, таком как git или svn. Частным случаем использование концепта «Все Как Код»‎ является использование практики Doc As a Code (документация как код), т.е. создание и публикация контента через использование тех же средств, что и при разработке приложений на любом из языков программирования.

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

Написание документации или ее части инженерами (аналитиками или инженерами) влияет на выбор инструментов. Разработка документов в концепции Doc As a Code означает выполнение следующих действий:

• работу с использованием простых текстовых редакторов и простых текстовых форматов (не используя бинарные форматы данных, таких как Adobe FrameMaker или Microsoft Word);

• отслеживание изменений в документах при помощи систем контроля версий (обычно это git-репозиторий) аналогично хранению программного кода (вместо хранения документов в другом пространстве, например, SharePoint или на общем диске);

• хранение документов вместе с исходным кодом проекта;

• взаимодействие с другими авторами, используя систему контроля версий для ветвления, слияния, отправки и извлечения обновлений (вместо совместной работы через большие системы управления контентом или сайты, подобные SharePoint);

• автоматизацию процесса сборки документов, аналогично тому, как это делается при сборке приложений;

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

• управление документами с использованием процессов, знакомых инженерам (например, Scrum, Agile), управление документацией в таск-трекере  (например, JIRA/Redmine/GitLab), распределение задач по спринтам и информирование заинтересованных сторон о готовности документации (показ демонстраций).

Итак, нам нужно решить следующие задачи при работе с документами:

• создание документов (технические задания, руководство пользователя, документация для API, описание архитектуры системы);

• поддержка форматирования и стилизация документов, использование шаблонов, экспорт в PDF или HTML;

• простая возможность контроля изменений;

• интеграция с существующим таск-трекером;

• возможность использования CI/CD для публикации документов;

• кроссплатформенность, возможность работы с использованием любой операционной системы.

Варианты, которые мы рассматривали 

Использование MS Word

Один из самых простых вариантов — использовать MS Word/Libre Office при разработке технических заданий и документов. Чаще всего формат doc/docx является стандартным по умолчанию для заказчиков. Даже когда используются системы типа корпоративных вики  (например, Confluence) выгрузка для конечного заказчика преобразуется  в формат doc/docx.

Плюсы данного решения:

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

• достаточная низкая learning curve (кривая обучения);

• не требует знаний языков разметки;

• расширяемость (плагины, шаблоны);

• экcпорт в различные форматы (PDF, HTML и другие).

Минусы:

• бинарный формат, не позволяющий использовать системы контроля версий для отслеживания изменений;

• сложности в сборке и форматировании больших документов; очень часто форматирование и расположение элементов после вставки текста получается в другом формате, необходимо менять форматирование;

• не кроссплатформенный, по факту сложное форматирование текста в Libre Office отличается от того, что отображается в MS Office;

• работа с комментариями доступна только внутри документа;

• покупка лицензий.

Использование Confluence

Confluence — тиражируемая вики-система, которая позволяет создавать страницы и документы, обмениваться ими и другим контентом между участниками команды. Платформа разрабатывается австралийской компанией Atlassian и является одним из двух ее основных продуктов (наряду с системой c Jira). Распространяется под проприетарной лицензией. Используется во многих компаниях  и отчасти тоже является стандартом по умолчанию при разработке документов.

Плюсы данного решения:

• поддержка любых платформ, можно использовать cloud hosting без разворачивания приложения в локальном дата-центре или сервере;

• Web 2.0, не нужны дополнительные редакторы для создания контента;

• низкая learning curve;

• расширяемость (плагины, API, шаблоны и т.п.);

• можно хранить бинарные документы, при этом сохранять версионность файлов;

• видны все изменения, есть полнотекстовый поиск;

• экспорт в различные форматы (PDF, Doc).

Минусы:

• покупка лицензий;

• покупка плагинов;

• для сквозной интеграции лучше использовать JIRA.

Использование LaTeX

LaTeX — это высококачественная система набора текста; она включает в себя функции, предназначенные для подготовки технической и научной документаций. LaTeX является стандартом де-факто для передачи и публикации научных документов.

Плюсы данного решения:

• кроссплатформенная система;

• доступно под лицензией LPPL V1.3;

• расширяемость (возможность написания своих шаблонов и макросов);

• большое количество готовых шаблонов;

• использование скриптов;

• экспорт в различные форматы (PS/PDF и HTML).

Минусы:

• достаточно высокая learning curve.

Использование Markdown

Markdown — облегчённый язык разметки, созданный с целью форматирования в простом тексте, с максимальным сохранением его читаемости человеком, и пригодный для экспорта в различные форматы (HTML, RTF и другие)

Плюсы данного решения:

• кроссплатформенность;

• простота модификации и настройки;

• низкая learning curve;

• есть свои IDE или плагины для существующих (IntelliJ IDEA, VS Code), в том числе online;

• использование скриптов;

• расширяемость (возможность написания своих шаблонов, команд);

• использование командной строки для поиска и модификации текста;

• используется по умолчанию в Gitlab, возможно создать шаблоны для задач в GitLab;

• экспорт в различные форматы (PDF, HTML и другие).

Минусы:

• нужно знать язык разметки;

• плохая поддержка сложного форматирования в таблицах, требуется использование HTML-разметки.

Использование AsciiDoc

AsciiDoc — это формат текстовых документов для написания заметок, документации, статей, книг, слайд-шоу, веб-страниц, man-страниц и блогов. Файлы AsciiDoc могут быть переведены с помощью инструментария Asciidoctor во многие форматы, включая HTML, PDF, EPUB, DocBook и man page. Можно использовать любой текстовый редактор.

Asciidoctor — это основной процессор AsciiDoc, который читает исходный файл в формате AsciiDoc, разбирает его на модели документа и преобразует в формат, пригодный для публикации. Например, PDF, с помощью конвертера. Asciidoctor имеет как CLI, так и API, которые можно использовать для вызова встроенного конвертера (HTML, DocBook, man page) или дополнительного. Asciidoctor обогащает PDF, который тот создает из AsciiDoc, применяя таблицу стилей по умолчанию, добавляя стилистические значки и подсвечивая исходные блоки.

Плюсы:

• кроссплатформенность;

• простота модификации и настройки;

• низкая learning curve;

• есть свои IDE или плагины для существующих (IntelliJ IDEA, VS Code);

• использование командной строки для поиска и модификации текста;

• расширяемость (возможность написания своих шаблонов, команд);

• экспорт в различные форматы.

Минусы:

• нужно знать язык разметки и специальные команды.

Результаты выбора

В итоге у нас был выбор  между использованием Markdown и AsciiDoc. Но поскольку важными преимуществами AsciiDoc были использование шаблонов и более широкие возможности форматирования без использования HTML, то мы выбрали AsciiDoc.

О том, как работать с AsciiDoc, расскажем в следующей части.

Продолжение следует —>