Пользовательская документация: как мы применили к ней лучшие мировые практики
Привет, Хабр! Я Костя Макушев, работаю техническим писателем в подразделении ИТ-Инфраструктуры Т-Банка. В этой статье расскажу, какие проблемы возникли с пользовательской документацией продуктов нашего подразделения и какие подходы мы начали применять, чтобы эти проблемы решить.
Статья будет полезна всем, кто занимается и интересуется документацией: техническим писателям, владельцам продуктов, менеджерам, тимлидам.
Общий контекст
Скажу пару слов о роли нашего подразделения в компании и про какую документацию пойдет речь.
В Т-Банке нет отделений, а все наши клиентские продукты и их поддержка опираются на ИТ-решения. У нас работают тысячи ИТ-специалистов, которым для раскатки ИТ-решений нужна технологическая основа: серверы, базы данных, хранилища, виртуальные машины, сеть, балансировщики и так далее. В общем, нужна ИТ-инфраструктура, которую и обеспечивает наше подразделение.
Подразделение ИТ-Инфраструктуры состоит из нескольких десятков команд, каждая из которых разрабатывает и поддерживает свой продукт, в том числе пишет к нему документацию. В статье речь пойдет только о документации, которая адресована пользователям — разработчикам платформы и высокоуровневых сервисов, внешним по отношению к команде инфраструктурного продукта.
Документация бывает еще внутренней, которую команда пишет для себя, и гостовской, которую готовят для официальных реестров. Эти виды документации требуют отдельного разбора, здесь я о них говорить не буду.
Проблемы пользовательской документации
В начале 2024 года основными «фичами» документации разных продуктов были разрозненность, неконсистентность и частичная неактуальность. В общем, типичная картина, когда документация живет без процессов и техписателя.
Из-за этих проблем пользователи тратили силы и время на поиск информации, команда — большие ресурсы на поддержку, а бизнес оплачивал все эти человеко-часы, которые могли быть потрачены с большей пользой.
Разберу подробнее каждый пункт и расскажу о том, какие проблемы для пользователей и всего бизнеса это создавало.
Разрозненность. Думаю, ИТ-специалистам знакома ситуация, когда база знаний в Confluence разрастается и без должного ухода превращается в кладбище разрозненных и отчасти устаревших статей, которым никто не доверяет и где никто не может ничего найти. Такой примерно и была наша ситуация, вдобавок умноженная на число продуктовых команд.
Основным инструментом ведения любой документации в командах было вики-пространство, причем у каждой команды свое. Пользовательская документация лежала отдельным подраздельчиком среди тонн внутрянки: рабочих регламентов, таблиц, процессных договоренностей и просто каких-то черновиков. Иногда внутренние документы просачивались в пользовательские разделы, а иногда, наоборот, нужные пользователям статьи выпадали наружу и терялись в рабочей документации.
Единой точки входа у документации не было, поэтому пользователь, который использовал для проекта сразу несколько продуктов инфраструктуры, терялся в вики-пространстве.
Что делает нормальный пользователь, который не нашел документацию за 5 секунд? Правильно, пишет свой вопрос в техподдержку. Больше пользователей — больше вопросов. И вот, часть команды вынуждена заниматься рутиной, показывая пользователям, где лежит док и где в нем нужная инфа.
Неконсистентность. Неизбежно возникает, когда документацию пишут без опоры на общие правила, и может проявляться на уровне структуры разделов, оформления, используемых формулировок и отдельных терминов. В нашем случае это был полный комплект.
В документации каждого продукта разделы были расположены по-своему, и у подразделов также часто не было структуры. Формулировки и оформление зависели от представлений их авторов о прекрасном, а одну сущность могли описывать несколько терминов.
Может показаться, что это чисто косметическая проблема, которая не стоит внимания. Ну да, немного некрасиво, везде немного по-разному, но ведь вся суть изложена верно, для пользователя это главное. На самом деле это вопрос скорости восприятия и передачи информации, то есть проблема эффективности.
Когда в документации разных продуктов разная структура и та зачастую непродуманная, пользователь тратит больше времени, чтобы найти ту информацию, за которой пришел. Разные подходы к оформлению и тяжелые формулировки отвлекают пользователя от восприятия сути. А про неконсистентность терминов вообще молчу.
Чем больше таких проблем в документации, тем выше риск, что пользователь бросит ее читать и пойдет в поддержку.
Неактуальность. Тут все просто. Любая документация развивающегося продукта быстро становится неактуальной, если в команде не настроены процессы документирования, кросс-ревью и сбора обратной связи. Вот вы выпустили новую фичу или поменяли интерфейс — хоба! Ваш док неактуален. Надо бы поправить, но кто и когда это сделает?!
На самом деле все еще хуже. Все ж мы люди, автор может что-то не учесть или забыть описать, поэтому документация может оказаться неполной или неточной уже в момент публикации.
Такая картина и наблюдалась у нас: часть информации в доке оказалась неполной, часть потеряла актуальность, а какие-то вещи вообще не были описаны. А пользователь в таких случаях, как мы уже знаем, идет в поддержку.
Решения
Чтобы решить проблемы, о которых я рассказал, мы применили несколько лучших практик, обычно используемых для документации:
перенесли документацию из вики-системы на отдельный сайт;
составили и внедрили редакционную политику;
настроили процессы документирования;
установили каналы прямой и обратной связи с пользователями.
Раскрывать подробности этих решений я буду по очереди, но хочу подчеркнуть, что сами решения внедрялись параллельно. Важен весь комплекс.
Решение 1. Единый сайт
Чтобы решить проблему разрозненности, мы начали поочередно переносить пользовательскую документацию всех продуктов ИТ-инфраструктуры на один сайт, где каждый продукт описан в своем разделе. Сайт стал для пользователей единой точкой входа в документацию и витриной наших продуктов. Для нас это важно, поскольку наше подразделение позиционируется как внутренний облачный сервис и мы хотим, чтобы пользователи знали о готовых решениях для их задач.
Сайт собирается из Markdown-файлов генератором статических сайтов на основе Docusaurus. Помимо стандартного Markdown-синтаксиса этот движок поддерживает MDX и React-компоненты, которые обеспечивают красивости:
инфоплашки для выделения важной информации;
раскрывающийся текст (каты), чтобы прятать технические детали;
вкладки для описания разных способов сделать одно и то же;
Mermaid-диаграмы, чтобы рисовать схемки Plain-текстом.
Чтобы не забегать вперед, другие подробности о том, как мы собираем и поддерживаем документацию на этом сайте, я расскажу чуть позже.
Решение 2. Редакционная политика
Чтобы решить проблему неконсистентности, мы составили редакционную политику — набор несложных правил, по которым мы договариваемся писать и оформлять текст документации.
Читатели, знакомые с типичными процессами работы с текстом, могут предположить, что это то же самое, что стайлгайд, — просто мы выбрали для него неудачное название. В нашем случае редакционная политика — всеобъемлющий документ, который включает:
общие принципы работы над документацией;
описание базовой структуры документации, которой мы придерживаемся для всех продуктов;
подход к работе с терминологией, включая правописание некоторых не устоявшихся в словарях терминов типа «бэкенд»;
правила оформления различных элементов текста: списков, таблиц, инфоплашек, блоков кода и так далее;
наконец, стайлгайд.
Подробное описание всех пунктов редполитики с примерами и объяснением, почему они именно такие, тянет на отдельную статью. Напишите в комментариях, если вам было бы интересно ее почитать, но здесь я только кратко раскрою самые интересные, на мой взгляд, аспекты: общие принципы, описание структуры и стайлгайд.
Общие принципы редполитики. В начале мы приводим общие принципы — краткое объяснение того, зачем инженеру читать эту редполитику, и краткое изложение философии документации. Здесь мы стараемся донести до читателя редполитики двойную ценность этого документа:
Для составителя документации. Заключается в том, чтобы упростить процесс написания текста. Когда у тебя есть правила и примеры, по которым нужно писать, делать это становится значительно легче.
Для пользователей. Заключается в том, чтобы снизить когнитивную нагрузку на пользователя со стороны текста. Текст документации не должен мешать извлекать из нее информацию о продукте. В идеале читатель вообще не должен задумываться о том, что перед ним какой-то текст.
Вся остальная редполитика направлена на обеспечение этих двух ценностей.
По-моему опыту, важно донести до команд, что задача редполитики не в том, чтобы запретить им писать как хочется или заставить писать определенным образом, а в том, чтобы упростить всем работу. Еще важно, чтобы редполитика не была слишком длинной и всеобъемлющей — только ключевые, самые распространенные элементы. Иначе никто не дочитает.
Структура документации. В основе структуры документации лежит подход Diátaxis, при котором вся информация о продукте делится на четыре раздела и попадает в тот или иной раздел в зависимости от того, какую задачу пользователя она решает:
объясняет, как устроен продукт (концепции);
объясняет, как решить задачи с помощью продукта (пошаговые инструкции);
учит пользоваться продуктом (туториалы);
перечисляет технические элементы и их назначение (справочники).
В силу специфики наших продуктов обязательными разделами в документации стали концепции и пошаговые инструкции. Почти любой наш продукт можно целостно описать через объяснение, как он устроен и как с ним работать. Остальные два раздела по Diátaxis у нас считаются опциональными, поскольку для них не всегда есть наполнение.
Например, в роли туториала для некоторых продуктов выступает только один раздел «Быстрый старт», который обучает пользователя основному сценарию работы через создание базовой тестовой конфигурации. Некоторые организационные аспекты работы с продуктом, например информацию о квотах, мы выносим на поверхность, чтобы пользователям было сложнее их пропустить.
Такой подход к структуре отвечает пользовательским запросам к документации и значительно упрощает написание документации для команд. Оформлять мысли из головы намного легче, когда понимаешь, куда тот или иной кусок информации положить.
Унифицированный подход к структуре документации в разных продуктах делает ее в целом более предсказуемой для пользователя. Прочитав док про один продукт, пользователь представляет, где и какую информацию он найдет в документации о соседнем продукте.
Стайлгайд. Набор рекомендаций о том, как мы формулируем предложения в тексте и как обращаемся к читателю. Пишем мы «Нжми кнопку», «Нажмите кнопку» или же используем всякие душные конструкции типа «Необходимо выполнить нажатие на кнопку» (мы не используем). В целом наш стайлгайд следует заветам Норы Галь и Максима Ильяхова, которые призывают отказаться от канцелярита, тяжелых конструкций и лишних слов.
Пункт стайлгайда может состоять из заезженной редакторской шутки, пояснения, почему на самом деле так писать не стоит, и примера того, как не надо делать и как надо:
Отглагольными существительными осуществлен вымост дороги в ад.
Отглагольные существительные создают канцелярский тон и требуют использовать другие канцелярские обороты, например страдательный залог. Отглагольные существительные почти всегда можно заменить на активный глагол.❌ В целях оптимизации потребления ресурсов платформы проводится мониторинг простаивающих инстансов.
✅ Система отслеживает простаивающие инстансы, чтобы они не занимали надолго ресурсы платформы.
Как и в случае со структурой разделов, назначение стайлгайда в том, чтобы сделать тексты более понятными и человекочитаемыми, единообразными во всей документации нашего подразделения.
В дополнение к редполитике отдельным документом мы сделали шаблоны для элементов оформления: таблиц, инфоплашек, вкладок и так далее. Как любой современный SSG, Docusaurus поддерживает больше различных элементов оформления, чем дефолтный Markdown, и каждый раз вводить для них теги руками — дело неблагодарное. Скопировать из шаблона в разы быстрее.
Скептичный читатель скажет: «Ну и что, ввели вы редполитику. А кто гарантирует, что разработчики и инженеры, которые пишут доки, станут ее строго придерживаться?» Иными словами, решает ли редполитика проблему неконсистентности сама по себе? Конечно, нет. И тут мы подходим к следующему пункту — процессам документирования.
Решение 3. Процессы документирования
В основе нашего нового процесса лежит подход Docs as Code, при котором для создания документации используются инструменты и методы разработчиков при написании кода. В нашем случае:
Документация хранится в GitLab-репозитории в виде набора Markdown-файлов, которые удобно редактировать в любом IDE.
Главная ветка репозитория собирается в готовую документацию генератором статических сайтов (SSG).
Изменения вносятся через процедуру Merge Request (MR). Каждый MR проходит ревью двух специалистов: технического писателя и члена команды разработки.
Подход дал нам множество преимуществ:
Документация стала ближе к разработчикам за счет использования знакомых и удобных для них инструментов и процедур. Замена WYSIWYG-редактора на Plain-текст позволяет не думать об оформлении и сосредоточиться на смысле написанного.
Репозиторий с документацией связан с Jira, и, если указать номер Jira-задачи в имени MR, он автоматически к ней прикрепится. Благодаря этому командам легче интегрировать процесс поддержки документации с общим процессом развития продукта.
GitLab обеспечивает контроль версий и удобный инструмент ревью. Коллега может предлагать автору свои правки, которые наглядно отобразятся в интерфейсе.
Каждый MR теперь проходит процедуру двойного ревью: со стороны команды разработки и со стороны технического писателя. Разработчик проверяет, что вносимое изменение отвечает фактам, а техпис следит за тем, чтобы соблюдалась структура, оформление, стиль и правописание. Один из возможных сценариев доработки документации описан ниже и показан на рисунке.
Процесс такой:
Разработчик решает написать раздел документации или дополнить существующий. Он знакомится с редполитикой и процессом контрибьюта, клонирует репозиторий с документацией и создает в нем свою ветку.
Разработчик вносит правки в своей ветке, пушит ее в GitLab и открывает MR.
Другой разработчик смотрит, что его коллега нигде не ошибся и все действительно работает так, как написано. Если все хорошо, ставит апрув.
Технический писатель проверяет, что предложенные правки отвечают редполитике и не содержат текстовых ошибок. При необходимости оставляет комментарии или сам вносит редакторские правки. Когда все проблемы текста решены, тоже ставит апрув.
Когда оба апрува получены, кто-то из участников, обычно автор MR, вливает изменения в главную ветку, которая автоматически обрабатывается SSG. В результате изменения отображаются у пользователя на сайте.
Возможны и другие сценарии работы. Например, документацию может писать техписатель на основе старой версии документации или после погружения в продукт. Но остальная часть процесса выглядит так же: ревью со стороны разработчика и со стороны другого техписателя (нас двое, как ситхов).
Как видите, в нашем процессе мы предполагаем, что разработчики прочитают редполитику, она поможет им писать и сократит число правок при ревью, но мы не рассчитываем, что они будут скрупулезно следовать ей, и не требуем этого от них. Обеспечение качества текста — профессиональная обязанность технического писателя, а не разрабов. Разработчики отвечают только за достоверность и полноту информации.
В итоге внедренные подходы позволили нам решить проблемы разрозненности и неконсистентности и повысить общее качество текста документации. О проблеме неактуальности скажем пока осторожно, что внедрение Docs as Code помогло нам уменьшить ее остроту. Для дальнейшего решения этой проблемы понадобились дополнительные меры, о которых ниже.
Решение 4. Связь с пользователями
Чтобы поддерживать актуальность документации и иметь лучшее представление о пользовательском опыте, мы наладили несколько каналов прямой и обратной связи с нашими пользователями:
Разместили ссылки на новую документацию в интерфейсах продуктов и каналах поддержки. Время от времени мы рассказываем о ней в наших новостных постах. Так пользователи узнают, что документация существует и как ее найти.
Некоторые команды внедрили у себя процесс регулярного обновления — документация еженедельно дополняется по итогам наиболее частых обращений пользователей в поддержку и изменений в продукте. Это помогает командам поддерживать актуальность документации и сократить число обращений по типовым вопросам.
Завели канал обратной связи по документации в корпоративном мессенджере. Пользователи могут сообщить в канал об обнаруженной ошибке, например, когда поведение продукта отличается от описанного. Это тоже помогает нам поддерживать документацию в актуальном состоянии.
Включили документацию в систему аналитики посещаемости, в которой мы можем оценить, какие страницы документации пользуются наибольшим спросом у пользователей.
Провели опрос среди пользователей продуктов, чтобы понять, знают ли они о нашей документации и что о ней думают.
Хотя опрос показал, что те, кто читал документацию, в основном довольны ее качеством, многие документацию не находят. Пока нам не удалось изменить сложившееся у пользователей представление, что спросить в поддержке проще, чем самому найти ответ в документации. Основным сценарием для части пользователей остается обращение в поддержку, которая уже направляет его на нужную страницу.
Для решения этой проблемы мы планируем интегрировать в документацию и каналы поддержки AI-инструменты, которые будут подсказывать пользователю, где он может найти ответ на свой вопрос. Но это история для другой статьи.
Что еще почитать
По академической привычке в завершение статьи я оставляю ссылки на материалы по теме:
Если вы в принципе сомневаетесь, нужна ли вам хорошая документация и стоит ли нанять техписателя, рекомендую почитать статью специально об этом.
Для размещения документации на отдельном сайте существует множество SSG. Я перечислю здесь только несколько опенсорсных, которые вы можете без ограничений использовать для любого проекта:
Sphynx — самый известный свободный SSG.
MkDocs — второй по популярности инструмент.
Diplodoc — SSG от Яндекса. Поддерживает всякие красивые и полезные фичи из коробки благодаря Yandex Flavored Markdown.
Docusaurus — красивый и довольно функциональный SSG, который мы и запилили под себя. Поддерживает MDX и React-компоненты.
О подходе, который мы применили к структурированию информации, читайте на сайте Diátaxis или в хабростатье.
Ничто так не помогает спроектировать и написать хорошую документацию, как чтение другой хорошей документации. Поделиться нашим внутренним доком я с вами не смогу, но приведу пару примеров сторонних публичных доков, которые сам считаю классными:
Yandex Cloud (на примере облачного PostgreSQL) — документация структурирована в духе Diátaxis и написана в хорошем стиле, без канцелярщины и воды. Считаю это одним из лучших примеров документации на русском языке. Сделана на SSG Diplodoc.
Godot (читается «Годо») — документация к опенсорсному игровому движку. Сделана на SSG MkDocs, поддерживает несколько локализаций, включая русскую. Прекрасные туториалы и в целом хороший пример того, как можно выстроить документацию сложного продукта для творчества, для которого не может быть инструкций.
Научиться писать легкий для восприятия текст вам поможет книга Максима Ильяхова и Людмилы Сарычевой «Пиши, сокращай». Еще я рекомендую почитать Нору Галь «Слово живое и мертвое» и Уильяма Зинсера «Как писать хорошо» (On writing well). Не рекламирую конкретные издательства и маркетплейсы, поэтому ссылок не даю.
Если эта статья была полезна, ставьте лайк, а если у вас остались какие-то вопросы, добро пожаловать в комментарии!
