Как сумасшедший исследователь, я уже пять лет пытаюсь создать идеальную документацию по продукту.
Но раз оно все еще не идеально, значит, я делаю что-то не так.
Об этом и будет статья.
Я хотел бы обрисовать путь, который мы прошли, и рассказать о том, какие решения мы приняли и что из этого выросло.
Коротко о продукте
Unidata занимает нишу в области управления ключевыми бизнес-данными.Используя нашу систему, вы можете объединять данные из всех источников, проверять и корректировать их, а затем регулировать работу с данными.
Все это помогает бизнесу быть уверенным в важных данных, а значит, снизить потери от ошибок и несоответствий.
Unidata — большой и сложный продукт, и управлять данными непросто.
Сама суть проекта порождает множество нюансов и вопросов, которые необходимо отразить в тексте.
Это одна из причин, почему наша документация становится более сложной с каждым выпуском.
С чем мы работаем
Сегодня объем нашего комплекта документации превысил миллион знаков — по объему он сопоставим с первыми двумя томами «Войны и мира»:
Таких комплектов у нас много — по одному на каждый релиз:
А недавно мы также создаем английскую локализацию:
Первый этап прост
Вначале было слово Слово.Задачи были простые и классические: описать все нововведения релиза, исправить возможные ошибки и сделать PDF-набор из исходного кода.
Когда начинался новый релиз, нужно было скопировать набор исходников и продолжать работу с ним, а старые версии оставались в качестве резервной копии.
Потом появилось:
- Метаданные.
В инструкции записана дата изменения, номер релиза, задание и комментарии.
Метаданные оказались чрезвычайно полезными.
- Двойная навигация (содержание + индекс).
Практика показала, что предметный указатель практически не используется.
Пользователи столкнулись с проблемами при навигации по огромным плоским документам:
- Неудобно искать похожие статьи в нескольких документах.
- Трудно найти нужную ноту.
- Скриншоты в PDF слишком маленькие.
- Все вложения были в текстовом виде.
Второй этап сложный
Когда неудобства Word достигли критической массы, я начал искать альтернативные решения.Их было довольно много, и они были разделены на разные категории:
- Расширения для Word и других текстовых редакторов.
- Технологии из одного источника.
- Генераторы статических сайтов.
- Вики-движки.
В «Докувики» разрешено:
- Разверните вики локально.
Это особенно полезно при размещении продуктов и помощи в замкнутом цикле.
- Расширьте функционал с помощью плагинов.
- Создайте свой собственный дизайн страницы.
Я изменил почти все, что попадалось под руку, включая шрифты, пропорции страниц и поддержку мобильных устройств.
- Распределите доступ к контенту для разных ролей пользователей.
- Разрешить конечным пользователям публиковать свою проектную документацию рядом с основной документацией.
- Удобно работать с картинками и таблицами.
Не идеально, но удобно.
- Переход на новый инструмент относительно быстрый.
Мы могли бы долго говорить о выборе, сравнивать инструменты, но я не уверен, что это интересно.
Если кратко, то на выбор повлияли: простота инструмента, развитое сообщество, широкие возможности и простота установки проекта.
Казалось бы, в царстве документации должен наступить рай.
Но нет. Мы еще не отказались от документов Word; теперь релизы делались сразу в двух системах.
Сначала классически, а потом перенесли на вики.
В конце релиза нужно было создать набор PDF-файлов из Word и создать архив из вики.
Кажется, они переиграли сами себя.
Почему это?
- Генерация PDF. «Докувики» может его сгенерировать, особенно с помощью специального плагина, но структура страницы и неработающие перекрестные ссылки не подходят.
- стандарты ГОСТ.
Мы должны быть удобными для тех, кто пишет документацию по ГОСТу на основе документации на продукцию.
Бизнес пока не готов отказаться от документации по ГОСТу, как и от PDF.
Теперь клиент может установить продукт, локально развернуть вики, указать хост и перейти из определенного раздела продукта на страницу, описывающую этот конкретный раздел.
После поиска в PDF или распечатке это кажется колдовством.
Такой способ работы мог бы жить еще долго, но продукт продолжает развиваться, и мы сталкиваемся с новыми проблемами.
Третий этап – современно и модно
Первой и очень серьезной задачей стал перевод всего нашего наследия на английский язык.Если бы мы писали книгу, мы бы просто перевели ее и положили конец.
Но документация — это текст, который постоянно меняется.
Нужно отслеживать правки в оригинале и сразу применять их в переводе, нужно обновлять скриншоты сразу в двух местах и т.д. и т.п.
Вторая задача заключалась в изменении подхода к инструкциям.
Честно говоря, мы хотим уйти от анатомического описания каждой кнопки и от слабо связанных между собой инструкций.
Хотелось бы не только фиксировать ход разработки, но и улучшить качество текста.
Потом мы выпустили новое поколение продукта, и ориентация документации на документы Word ослабла.
Мы решили постепенно переходить на формат онлайн-справки, а это значит, что справка должна быть не только на двух языках, но и позволять переключаться между выпусками продуктов.
Это стало третьей задачей.
Мы пробовали экспериментировать с пространствами имен и хостами в «Докувики».
Как и ожидалось, это подходит только как временное решение.
Работать с локализациями еще можно, но управлять версиями документации в «Докувики» очень неудобно.
Однако мы все еще работаем с «Докувики».
Новые задачи создают ряд проблем, ломают удобные схемы, доводят нас до отчаяния — в общем, делают все, чтобы мы перешли к более зрелому подходу к документации.
Я считаю этот подход концепцией Документы как код .
Новый инструмент был найден на удивление быстро.
Вариантов было не более 5, и я остановился на Сфинкс-док .
Что уже сделано:
- Мы развернули собственный проект в Sphinx и разместили его в Gitlab.
- Нам удалось сделать такой же дизайн страницы, как в нашей «Докувики».
- Возвращаемые метаданные в виде комментариев.
reStructuredText позволяет это.
- Мы организовали совместную работу.
На этот раз не только с техническими заметками, но и с разработчиками.
- Организованное управление контентом на разных языках.
- Поддержка i18n и переключение.
- Поддержка и переключение релизов документации.
- Упрощение создания таблиц.
- Создание PDF-файлов и настройка их шаблонов.
- Настройка Google Аналитики.
- Автоматическая проверка ссылок.
- Что-то еще, чего мы еще не видели.
PDF-документация в конечном итоге должна будет появиться не через Word, а из Sphinx. Онлайн-справка должна измениться с «Докувики» на «Сфинкс».
О недостатках и точках роста
И в заключение немного о наших недостатках и проблемах.Я думаю, что этим тоже важно поделиться.
- Мы вынуждены расставить приоритеты таким образом, чтобы улучшение качества текста оставалось на нижних позициях.
Это следствие гонки за релизами, работы над переводами и другой не менее важной деятельности.
В обозримом будущем ситуация потенциально улучшится.
- Документация рассчитана только на 2 категории пользователей и не учитывает интересы еще нескольких категорий.
Мы начали работать над исправлением этой ситуации, но проблема будет сохраняться еще некоторое время.
- Нам сложно собирать отзывы по документации от клиентов.
Здесь все просто: никто бесплатно анализировать не будет, насколько приятным, понятным и удобным было чтение.
Поэтому вам нужно работать с косвенными признаками, в том числе с Google Analytics.
- Слишком быстрые изменения в продукте.
Это имеет плохой эффект не потому, что у нас нет времени документировать, а потому, что любой устоявшийся текст может оказаться неактуальным уже через несколько месяцев после его написания.
Часть усилий просто пойдет насмарку.
- Отсутствие рук.
Боль распространена.
Для нас это выражается в том, что у нас недостаточно ресурсов для инженерного сопровождения процесса документирования.
Тот же Сфинкс глохнет, так как нужно потратить довольно много времени, чтобы всё настроить как надо.
Также мы экспериментируем с обучающими видео и другими форматами.
Возможно, в следующий раз мы поговорим об этом.
Теги: #Управление продуктом #Подготовка технической документации #документация #docsascode #баги и грабли
-
Фраунгофер, Йозеф
19 Oct, 24 -
Prepd Pack – «Умный» Ланчбокс
19 Oct, 24 -
Внимание! Уязвимость В Plesk
19 Oct, 24 -
Чего Не Хватает Носимым Устройствам
19 Oct, 24 -
Отчет Погорельцев
19 Oct, 24 -
Новые Вакансии Для Студентов-Практикантов
19 Oct, 24 -
Microsoft Выбирает Postfix
19 Oct, 24 -
Прощайте, Google Карты
19 Oct, 24
