Максим Кулагин, руководитель отдела технической поддержки, C3D Labs, рассказывает о форматах и средствах работы с документацией в компании.
Поговорим о подготовке документации: что у нас было, что делается сейчас и к чему мы стремимся. Учитывая разнообразие компонентов и способов доставки материалов, у нас сформировались разные форматы пользовательской документации (рис. 1).
1. Технология «DOC as Code»
Файл changes.txt поставляется вместе с дистрибутивом — он входит в архив. Это обычный текстовый файл с перечнем изменений, которые вносят разработчики. Вся документация представлена на нашем сайте, файл changes.txt доступен на странице «Для разработчиков».
Основная документация создана с использованием технологии Doxygen. Она формируется автоматически на основе комментариев в заголовочных файлах кода
Особняком стоит документация для компонента C3D Web Vision, поскольку этот компонент использует другие технологии и имеет иную структуру. Ее формируют с помощью системы Sphinx. Исходные файлы пишутся в формате Markdown, а затем из них автоматически генерируется сайт.
Наконец, подробная документация представлена в формате PDF. В ней даются развернутые описания — как работать с компонентами, какие бывают классы поверхностей, топологических объектов, как функционируют, например, конвертеры. Эта документация вызывает наибольшие сложности с изменениями. Изначально она создается в формате ODF (OpenDocumentFormat) — открытом аналоге DOC. С одной стороны, это дает визуально приятный документ, в который удобно вставлять изображения. С другой — технология имеет ряд проблем.
Назовем эту технологию «DOC as DOC». Какие же проблемы возникают на практике? Первая заключается в том, что в одном файле хранится и содержимое, и информация о форматировании, и изображения. Выделить каждую часть по отдельности достаточно сложно. Проблема номер два связана со сложностью организации совместной работы разработчиков над документами. Наша документация достаточно объемна и включает описание практически всех разделов компонентов C3D Toolkit. Когда несколько разработчиков одновременно вносят изменения, возникает проблема синхронизации. И с документами формата DOC выполнять синхронизацию в принципе затруднительно.
Сам формат не является текстовым: это zip-файл, внутри которого находятся XML, метаданные, изображения. Работать с ним в многопользовательском режиме затруднительно без специальных средств.
Есть и еще одна проблема — сложность преобразования документа в другие форматы, отличные от PDF. Именно PDF остается самым простым вариантом получения копии документа для печати. Однако и с форматом PDF возникают трудности, в большей степени из-за того, что используется не DOC, а ODF и форматирование часто нарушается. Изменив одну строку в начале, можно получить искаженный результат во второй половине документа.
В качестве альтернативы все чаще применяется подход «Doc as Code» (рис. 2). Поскольку мы программисты, логично работать с документацией так же, как с исходным кодом. Код хранится в системе контроля версий — в нашем случае это Git. Исходные файлы документации — обычные текстовые. Их легко читать, сравнивать, обрабатывать самыми простыми инструментами. Git содержит встроенную утилиту для сравнения таких файлов.
2. Применяемые форматы документации
Когда необходимо выдать документацию, выполняется сборка в выбранный формат. Она легко настраивается и может запускаться автоматически. Как код отправляется в компилятор, так и документация собирается в требуемый формат с помощью соответствующего инструмента. Данная технология гораздо лучше соответствует парадигме разработки и позволяет избежать множества проблем с документацией. А меньшее количество проблем означает, что процесс становится проще и качественнее, а документация поддерживается в актуальном состоянии.
Существует множество вариантов реализации такого подхода. Список решений можно продолжать почти бесконечно. Например, к ним относится Sphinx. У каждого из этих решений есть как преимущества, так и недостатки. Мы сформулировали определенные требования к системе. Это, в частности, текстовый формат исходной документации, поддержка встроенных изображений, возможность разделения форматирования и содержания. Еще один важный критерий — возможность создания сложных математических формул, поскольку в нашей документации такие формулы есть, а обычными средствами их реализовать затруднительно.
Из множества решений, в том числе с учетом мнений различных команд разработчиков, мы выбрали технологию LaTeX. На данный момент этот выбор уже сделан, и работы ведутся именно в этом формате. Среди достоинств можно отметить то, что это открытое и бесплатное программное обеспечение. Исходные файлы, разумеется, имеют текстовый формат.
Формат LaTeX, изначально разработанный в академической среде, позволяет создавать сложные математические выражения, что для нас крайне важно. Итоговый документ может включать иллюстрации, поддерживает автоматическую нумерацию, а также встроенные алгоритмы, автоматизирующие генерацию отдельных элементов документа (нумерация страниц, разделов, абзацев, рисунков и т. д.).
Кроме того, LaTeX позволяет разнести форматирование и текстовое содержимое по разным файлам, что очень удобно: можно задать разные шаблоны оформления для различных вариантов вывода. Немаловажным фактором стало и то, что данный формат широко распространен среди физиков и математиков, которых немало среди наших специалистов.
Мы получаем множество запросов о том, чтобы сделать нашу документацию более понятной, полной, актуальной и насыщенной примерами. Именно поэтому в команду технической поддержки принят новый сотрудник — технический писатель, который будет заниматься исключительно документацией.
Переход от формата ODT к TeX уже практически завершен. Остаются лишь отдельные задачи по доработке форматирования и интеграции с системой непрерывной сборки. Мы стремились четко разделить содержательную часть и оформление. Все, что можно автоматизировать, мы автоматизируем — это минимизирует влияние человеческого фактора. Настройка CI для автоматической генерации PDF-документов уже в процессе.
Наша цель — не просто получить PDF-файлы, но и предоставить удобную веб-версию документации. В современном мире пользователи хотят находить нужную информацию быстро, используя поисковую строку. Идея в том, чтобы по запросу, например «как в ядре C3D выполнить булеву операцию», пользователь сразу попадал на конкретную страницу с описанием нужной функции.
После завершения технической настройки мы сосредоточимся на содержании: добавим множество новых примеров, которые уже сейчас собираются и систематизируются. Наличие выделенного сотрудника и правильно организованный процесс работы с документацией позволят нам оперативно поддерживать ее в актуальном состоянии. Ожидаемый результат — полноценное, подробное и регулярно обновляемое описание возможностей ядра, доступное в разных форматах и удобное как для чтения, так и для поиска. Это облегчит освоение нашего ПО и ускорит вашу работу с компонентами C3D Toolkit.
Максим Кулагин,
руководитель отдела технической поддержки,
C3D Labs
