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

Хочу очертить тот путь, который мы прошли, и рассказать о том, какие решения принимали, и что из этого вырастало.

Коротко о продукте

"Юнидата" занимает нишу в области управления ключевыми данными бизнеса. С помощью нашей системы вы можете объединить данные из всех источников, проверить и исправить их, а впоследствии и регулировать работу с данными. Всё это помогает бизнесу быть уверенными в важных данных, а значит, снизить потери от ошибок и нестыковок.

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

С чем мы работаем

Сегодня объем комплекта нашей документации перевалил за миллион символов – по объему это сопоставимо с первыми двумя томами «Войны и мир»:

Таких комплектов у нас много – по одному на каждый релиз:

А с недавнего времени мы ещё создаем английскую локализацию:

Первый этап - простой

В начале было слово Word. Задачи были простыми и классическими: описать все нововведения релиза, исправить возможные ошибки, и сделать из исходников набор PDF. Когда начинался новый релиз, то нужно было скопировать набор исходников, и уже в нём продолжать, а старые версии оставались как бэкап.

Тогда появились:

• Метаданные. В инструкциях фиксировали дату изменения, номер релиза, задачу и комментарии. Метаданные оказались крайне полезными.

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

Со временем релизов стало больше, а сам комплект стал расширяться. И пользователи столкнулись с проблемами навигации по огромным плоским документам:

• Неудобно искать связанные статьи в нескольких документах.

• Тяжело найти нужное примечание.

• Скриншоты в PDF мелковаты.

• Все вложения были в виде текста.

Второй этап - затейливый

Когда неудобства Word'a достигли критической массы, я начал искать альтернативные решения. Их оказалось довольно много, и делились они на разные категории:

• Расширения для Word и другие текстовые редакторы.

• Технологии единого источника.

• Генераторы статичных сайтов.

• Вики-движки.

После долгих размышлений и тестов я остановился на вики-движке под названием Dokuwiki, так как он отвечал многим критериям и хотелкам. Dokuwiki позволил:

• Разворачивать вики локально. Это особенно полезно при размещении продукта и справки в закрытом контуре.

• Расширить функциональность через плагины.

• Создать собственный дизайн страниц. Я изменил почти всё, до чего дотянулся - включая шрифты, пропорции страниц и поддержку мобильных устройств.

• Распределить доступ к контенту для разных ролей пользователей.

• Разрешить конечным пользователям размещать собственную проектную документацию рядом с основной документацией.

• Удобно работать с картинками и таблицами. Не идеально, но удобно.

• Переехать на новый инструмент сравнительно быстро.

Мы потеряли только метаданные, но этот вопрос потенциально можно решить несколькими способами.

О выборе можно было бы говорить долго, посравнивать инструменты, но я не уверен, что это интересно. Если быть кратким, то на выбор повлияло: простота инструмента, развитое сообщество, широкие возможности и лёгкость установки проекта.

Казалось бы, должен наступить рай в царстве документации. Но нет. Мы ещё не отказались от вордовских документов, теперь релизы делались сразу в двух системах. Сначала классически, а потом переносилось в вики. В конце релиза нужно было создать набор PDF из ворда и сформировать архив с вики. Вроде как сами себя переиграли.

Почему так?

1. Генерация PDF. Dokuwiki умеет в генерацию, особенно со специальным плагином, но структура страниц и обломанные перекрестные ссылки не подходят.

2. ГОСТы. Мы должны быть удобными для тех, кто пишет гостовскую документацию на основе продуктовой. Бизнес ещё не готов отказываться от гостовской документации, как и от PDF.

Но есть и позитивный момент. Мы сделали в продукции контекстную справку вики. Теперь заказчик может установить у себя продукт, локально развернуть вики, указать хост, и перейти из определенного раздела продукта на страницу, в которой описывается именно этот раздел. После поисков в PDF или распечатке это кажется колдовством.

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

Третий этап - современный и модный

Первой, и очень серьёзной задачей, стал перевод всего нашего наследия на английский язык. Если бы мы писали книгу, то мы бы просто перевели её и на этом выдохнули. Но документация это текст, который меняется постоянно. Нужно отслеживать правки в оригинале и тут же применять их в переводе, нужно обновлять скриншоты сразу в двух местах и т.д., и т.п.

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

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

Мы пытались играться в Dokuwiki с пространствами имён и хостами. Как и ожидалось, это всё подходит только в качестве временного решения. Если работать с локализациями ещё можно, но вот управление версиями документации в Dokuwiki очень неудобно. Тем не менее, мы пока ещё работаем с Dokuwiki.

Новые задачи создают ряд проблем, ломают удобные схемы, вгоняют в фрустрацию - в общем, делают всё, чтобы мы переходили на более зрелый подход к документации. Таким подходом я считаю концепцию Docs as code.

Новый инструмент нашелся на удивление быстро. Альтернатив было не больше 5 штук, и я остановился на Sphinx-doc. Что уже получилось сделать:

• Мы развернули собственный проект в Sphinx и разместили его в Gitlab.

• Удалось сделать такой же дизайн страниц, как в нашей Dokuwiki.

• Вернули метаданные в виде комментариев. reStructuredText это позволяет.

• Организовали совместную работу. На этот раз не только с техписами, но и с разработчиками.

• Организовали менеджмент контента на разных языках.

<Сейчас мы здесь>

Нам предстоит ещё несколько доработок проекта, прежде чем мы полностью мигрируем на Sphinx.

В планах:

• Поддержка и переключение i18n.

• Поддержка и переключение релизов документации.

• Упрощение создания таблиц.

• Генерация PDF, и настройка их шаблонов.

• Настройка гугл аналитики.

• Автоматическая проверка ссылок.

• Что-то ещё, что мы пока что не увидели.

Сегодня мы пишем документацию сразу в трёх видах. PDF документация должна будет со временем появляться не через Word, а из Сфинкса. Онлайн-справка должна смениться с Dokuwiki на Сфинкс.

О минусах и точках роста

И в завершение немного о наших недостатках и проблемах. Я считаю, что этим тоже важно делиться.

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

2. Документация рассчитана только для 2 категорий пользователей, и не учитывает интересы еще нескольких категорий. Мы начали работу над исправлением этой ситуации, но какое-то время проблема еще будет сохраняться.

3. Нам сложно собирать обратную связь по документации от заказчиков. Тут всё просто: никто не будет бесплатно и просто так анализировать насколько чтение было приятным, понятным и удобным. Поэтому нужно работать с косвенными признаками, в том числе, с гугл аналитикой.

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

5. Нехватка рук. Болячка повсеместная. У нас она выражается в том, что у нас не хватает ресурса для инженерной поддержки процесса документирования. Тот же Sphinx буксует, так как нужно довольно много времени потратить чтобы настроить всё как дóлжно.

Я рассказал только про развитие основного текста документации. Ещё мы экспериментируем с обучающими видео и другими форматами. Возможно, в следующий раз поговорим об этом.