Documentat.io

KCS

Миграция документации из DOCX в Git. Аутсорс-команда техписателей. Долгосрочная поддержка.

Заказчик несколько лет бессистемно вел поддержку документации. Писали все: разработчики, менеджеры, техписатели из других отделов. Это отвлекало их от основных задач и тормозило весь процесс разработки. Вдобавок, каждый сотрудник писал на свой лад. Итогом стали 500 страниц без общего стиля, четкой структуры и навигации.

Отдельный ресурс на разработку документации так и не выделили – в итоге она сильно отстала от самого продукта. В какой-то момент документация отстала от ПО на 2 версии, или 6 месяцев.

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

Для начала мы полностью разгрузили команду заказчика и сами актуализировали документацию.

Далее мы серьезно обновили инструментальный стек. Раньше документация писалась в MS Word, (.docx). Теперь она на легковесном языке разметки reStructuredText (RST), из которого генерируются DOCX, PDF и HTML-версии. Всю документацию мы переместили в Git, настроили CI/CD-конвейер публикации, внедрили workflow управления документацией в JIRA.

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

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

Крупный комплект документации к программному продукту (руководства пользователя и администратора, инструкции по развертыванию, всего более 500 страниц) написан в MS Word, хранится и распространяется в формате DOCX.

Поддержка документации в DOCX сложна: сравнивать версии файлов и отслеживать историю изменений крайне неудобно, нет возможности трекинга изменений между кодом и документацией.

Документация создавалась в течение нескольких лет разными людьми: стиль и оформление текста неоднородны, структура и навигация нелогичны.

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

Накоплен «документационный долг»: документация отстает от развития продукта.

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

Полностью отдать документацию в ответственность команды documentat.io: в рамках проекта команда заказчика привлекалась только для разовых устных консультаций.

Перевести документацию из DOCX в plaintext-язык разметки RST.

Разместить RST-документацию в Git-репозитории заказчика рядом с кодом продукта.

Разделить содержимое и представление документации: хранить в репозитории только RST-исходники документации, а для генерации из них DOCX создать специальный инструментарий и запускать публикацию по требованию.

Дополнительно настроить публикацию документации в PDF и HTML в виде многостраничного веб-портала.

«Документационный долг» был аннулирован: вся недостающая функциональность была задокументирована, обновленная документация выпущена к дате релиза.

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

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

Все DOCX-документы были переведены в формат RST и размещены в Git-репозитории заказчика.

На базе Pandoc, python-docx и Sphinx было создано решение, публикующее RST в HTML, DOCX и PDF в корпоративной айдентике заказчика. Настроен CI/CD-конвейер, автоматически генерирующий и публикующий HTML, DOCX- и PDF-версии документации после каждого коммита.

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

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

Поддержка и развитие комплекта документации сейчас полностью ведется командой documentat.io.