Подобно безумному исследователю, я вот уже пятый год пытаюсь создать идеальную продуктовую документацию. Но, раз она всё еще не идеальна, значит я что-то делаю не так. Вот про это и будет статья.
Хочу очертить тот путь, который мы прошли, и рассказать о том, какие решения принимали, и что из этого вырастало.
Коротко о продукте
"Юнидата" занимает нишу в области управления ключевыми данными бизнеса. С помощью нашей системы вы можете объединить данные из всех источников, проверить и исправить их, а впоследствии и регулировать работу с данными. Всё это помогает бизнесу быть уверенными в важных данных, а значит, снизить потери от ошибок и нестыковок.
"Юнидата" - большой и сложный продукт, да и управление данными не из простых. Сама суть проекта рождает множество нюансов и вопросов, которые нужно отражать в тексте. Это одна из причин, почему наша документация усложняется с каждым релизом.
С чем мы работаем
Сегодня объем комплекта нашей документации перевалил за миллион символов – по объему это сопоставимо с первыми двумя томами «Войны и мир»:
Таких комплектов у нас много – по одному на каждый релиз:
А с недавнего времени мы ещё создаем английскую локализацию:
Первый этап - простой
В начале было слово Word. Задачи были простыми и классическими: описать все нововведения релиза, исправить возможные ошибки, и сделать из исходников набор PDF. Когда начинался новый релиз, то нужно было скопировать набор исходников, и уже в нём продолжать, а старые версии оставались как бэкап.
Тогда появились:
Метаданные. В инструкциях фиксировали дату изменения, номер релиза, задачу и комментарии. Метаданные оказались крайне полезными.
Двойная навигация (содержание + предметный указатель). Практика показала, что предметный указатель почти не используется.
Со временем релизов стало больше, а сам комплект стал расширяться. И пользователи столкнулись с проблемами навигации по огромным плоским документам:
Неудобно искать связанные статьи в нескольких документах.
Тяжело найти нужное примечание.
Скриншоты в PDF мелковаты.
Все вложения были в виде текста.
Второй этап - затейливый
Когда неудобства Word'a достигли критической массы, я начал искать альтернативные решения. Их оказалось довольно много, и делились они на разные категории:
Расширения для Word и другие текстовые редакторы.
Технологии единого источника.
Генераторы статичных сайтов.
Вики-движки.
После долгих размышлений и тестов я остановился на вики-движке под названием Dokuwiki, так как он отвечал многим критериям и хотелкам. Dokuwiki позволил:
Разворачивать вики локально. Это особенно полезно при размещении продукта и справки в закрытом контуре.
Расширить функциональность через плагины.
Создать собственный дизайн страниц. Я изменил почти всё, до чего дотянулся - включая шрифты, пропорции страниц и поддержку мобильных устройств.
Распределить доступ к контенту для разных ролей пользователей.
Разрешить конечным пользователям размещать собственную проектную документацию рядом с основной документацией.
Удобно работать с картинками и таблицами. Не идеально, но удобно.
Переехать на новый инструмент сравнительно быстро.
Мы потеряли только метаданные, но этот вопрос потенциально можно решить несколькими способами.
О выборе можно было бы говорить долго, посравнивать инструменты, но я не уверен, что это интересно. Если быть кратким, то на выбор повлияло: простота инструмента, развитое сообщество, широкие возможности и лёгкость установки проекта.
Казалось бы, должен наступить рай в царстве документации. Но нет. Мы ещё не отказались от вордовских документов, теперь релизы делались сразу в двух системах. Сначала классически, а потом переносилось в вики. В конце релиза нужно было создать набор PDF из ворда и сформировать архив с вики. Вроде как сами себя переиграли.
Почему так?
Генерация PDF. Dokuwiki умеет в генерацию, особенно со специальным плагином, но структура страниц и обломанные перекрестные ссылки не подходят.
ГОСТы. Мы должны быть удобными для тех, кто пишет гостовскую документацию на основе продуктовой. Бизнес ещё не готов отказываться от гостовской документации, как и от PDF.
Но есть и позитивный момент. Мы сделали в продукции контекстную справку вики. Теперь заказчик может установить у себя продукт, локально развернуть вики, указать хост, и перейти из определенного раздела продукта на страницу, в которой описывается именно этот раздел. После поисков в PDF или распечатке это кажется колдовством.
Такая схема работы могла бы жить долго, но продукт продолжает развиваться, и перед нами встают новые задачи.
Третий этап - современный и модный
Первой, и очень серьёзной задачей, стал перевод всего нашего наследия на английский язык. Если бы мы писали книгу, то мы бы просто перевели её и на этом выдохнули. Но документация это текст, который меняется постоянно. Нужно отслеживать правки в оригинале и тут же применять их в переводе, нужно обновлять скриншоты сразу в двух местах и т.д., и т.п.
Второй задачей стало изменение подхода к инструкциям. Признаться, мы хотим уйти от анатомического описания каждой кнопки, и от слабо связанных между собой инструкций. Хочется не только фиксировать ход разработки, но и улучшать качество текста.
Затем мы выпустили новое поколение продукта, и фокус документации на вордовских документах ослабел. Мы решили постепенно переходить к формату онлайн-справки, а, значит, справка должна быть не только на двух языках, но и позволять переключаться между релизами продукта. Это стало третьей задачей.
Мы пытались играться в Dokuwiki с пространствами имён и хостами. Как и ожидалось, это всё подходит только в качестве временного решения. Если работать с локализациями ещё можно, но вот управление версиями документации в Dokuwiki очень неудобно. Тем не менее, мы пока ещё работаем с Dokuwiki.
Новые задачи создают ряд проблем, ломают удобные схемы, вгоняют в фрустрацию - в общем, делают всё, чтобы мы переходили на более зрелый подход к документации. Таким подходом я считаю концепцию Docs as code.
Новый инструмент нашелся на удивление быстро. Альтернатив было не больше 5 штук, и я остановился на Sphinx-doc. Что уже получилось сделать:
Мы развернули собственный проект в Sphinx и разместили его в Gitlab.
Удалось сделать такой же дизайн страниц, как в нашей Dokuwiki.
Вернули метаданные в виде комментариев. reStructuredText это позволяет.
Организовали совместную работу. На этот раз не только с техписами, но и с разработчиками.
Организовали менеджмент контента на разных языках.
<Сейчас мы здесь>
Нам предстоит ещё несколько доработок проекта, прежде чем мы полностью мигрируем на Sphinx.
В планах:
Поддержка и переключение i18n.
Поддержка и переключение релизов документации.
Упрощение создания таблиц.
Генерация PDF, и настройка их шаблонов.
Настройка гугл аналитики.
Автоматическая проверка ссылок.
Что-то ещё, что мы пока что не увидели.
Сегодня мы пишем документацию сразу в трёх видах. PDF документация должна будет со временем появляться не через Word, а из Сфинкса. Онлайн-справка должна смениться с Dokuwiki на Сфинкс.
О минусах и точках роста
И в завершение немного о наших недостатках и проблемах. Я считаю, что этим тоже важно делиться.
Мы вынуждены выстраивать приоритеты таким образом, что улучшение качества текста остаётся на нижних позициях. Это следствие гонки за релизами, работы над переводами, и других не менее важных активностей. Потенциально в обозримом будущем этот момент будет улучшаться.
Документация рассчитана только для 2 категорий пользователей, и не учитывает интересы еще нескольких категорий. Мы начали работу над исправлением этой ситуации, но какое-то время проблема еще будет сохраняться.
Нам сложно собирать обратную связь по документации от заказчиков. Тут всё просто: никто не будет бесплатно и просто так анализировать насколько чтение было приятным, понятным и удобным. Поэтому нужно работать с косвенными признаками, в том числе, с гугл аналитикой.
Слишком быстрые изменения в продукте. Это плохо влияет не потому, что мы не успеваем документировать, а потому, что любой устоявшийся текст может быть неактуальным уже через месяца после написания. Часть усилий будет просто улетать в трубу.
Нехватка рук. Болячка повсеместная. У нас она выражается в том, что у нас не хватает ресурса для инженерной поддержки процесса документирования. Тот же Sphinx буксует, так как нужно довольно много времени потратить чтобы настроить всё как дóлжно.
Я рассказал только про развитие основного текста документации. Ещё мы экспериментируем с обучающими видео и другими форматами. Возможно, в следующий раз поговорим об этом.
