О важности документации на проекте знают все. Для нормальной работы нужен весь спектр, начиная от технических заданий на реализацию, заканчивая пользовательской документацией. Об этом написано множество статей.
Здесь мы с моим коллегой Алексеем Васильевым (@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, расскажем в следующей части.
Продолжение следует -->
