Привет, Хабр!
Меня зовут Алиса Комиссарова, я руководитель отдела автоматизации и поддержки документирования Positive Technologies.
Если вы работаете техническим писателем, скорее всего, ваши задачи ограничиваются разработкой пользовательской документации для одного продукта или направления. Вы привыкли пользоваться популярными инструментами документирования, знаете их основные функции и умеете писать и публиковать руководства. Но что поменяется, если перед вами встанет задача поддержать документацию для всех продуктов компании, охватывающую множество подсистем, версий, платформ, аудиторий и все этапы жизненного цикла продуктов? Достаточно ли будет знания руководства по стилю и общих принципов написания текстов?
Еще десять лет назад команде технических писателей Positive Technologies поставили именно такой вызов — компания активно росла и требовалось построить единую систему документирования. В этой статье я собрала практические рекомендации, которые помогут вам перейти от локального к корпоративному подходу, а также понять, для чего нужна роль архитектора контента.
Выбор инструмента
Чтобы построить корпоративную систему документирования, сперва нужно выбрать общий инструмент для всех авторов. Он позволит создавать, редактировать, сохранять и публиковать различный продуктовый контент как в виде электронных документов, так и в виде онлайн‑справки. Правильно выбрав инструмент, вы создадите надежную основу для единообразной и управляемой документации.
При выборе инструмента для продуктовой документации обратите внимание на следующие возможности:
Инструментарий для форматирования текста. Широкий выбор абзацных и символьных стилей, а также возможность создавать собственные (для текста, изображений, чек‑листов, прайс‑листов, форм и т. п.).
Масштабируемость при увеличении нагрузки. Поддержка одновременной работы большого количества авторов и эффективное управление растущим объемом контента.
Удобная локализация. Просмотр истории и статусов перевода, автоматическая выгрузка контента на перевод при изменении исходных материалов, поддержка перевода глоссария.
Согласование и вычитка. Хранение комментариев, ведение журнала изменений, генерация отчетов о вычитке, создание понятного интерфейса для редакторов и рецензентов.
Кастомизация. Возможность расширять свойства объектов (например, присваивать вариант книжной или альбомной ориентации таблицам или выбирать язык программирования для блока кода, чтобы определить способ подсветки синтаксиса), добавлять метаданные и интегрировать инструмент в существующие бизнес‑процессы (например, через API, плагины или скрипты).
Архитектор контента поможет вам оценить соответствие инструмента вашим реальным информационным потребностям, масштабируемость структуры данных и будущие расходы на поддержку контента. О том, как мы выбирали инструмент для корпоративного управления контентом, можно почитать здесь.
Согласно нашему опыту и опыту коллег из отрасли, этот этап перехода к корпоративной системе управления контентом может занять от двух месяцев до нескольких лет.
Структурирование контента в базе
Когда инструмент выбран, вы можете приступить к миграции вашего контента или к его созданию с нуля. Для старта работ необходимо договориться о правилах. Без четкой структуры информация превращается в хаотичный массив, который невозможно эффективно использовать ни на веб‑сайтах, ни на корпоративных порталах. Продуманная архитектура данных в базе и репозитории дадут вам ряд преимуществ:
Переиспользование — проектируйте контент как набор независимых, переиспользуемых блоков, а не как разделы документов. Каждый фрагмент должен решать одну задачу и тогда он может жить в разных контекстах.
Автоматизация обработки — при правильной организации можно применять единые правила к целым группам однотипных объектов (массовое обновление, переименование, миграция и т. д.).
Ускоренный поиск — четкая иерархия тем, типов и меток позволяет авторам быстро находить нужный материал, придерживаться единого формата и исключать дублирование контента.
Контроль доступа — структурированный контент упрощает настройку прав: к конфиденциальным разделам можно ограничить просмотр, а права на редактирование отдельных категорий контента предоставить только ведущим специалистам.
Архитектор контента определяет логическую организацию информации, ее взаимосвязи, правила хранения и доступности для пользователя. Он разрабатывает единые соглашения для всех авторов компании и контролирует их соблюдение.
Согласованный и четкий подход к хранению контента позволяет нам одновременно поддерживать маркетинговые материалы, техническую и проектную документацию, а также ресурсы для продаж, пилотирования и другие типы материалов. Так, например, за один рабочий день мы можем выпустить обновление EULA для 26 продуктов компании на нескольких языках локализации. Готовая EULA синхронно размещается на справочном портале (см. раздел «Лицензионное соглашение») и включается в дистрибутивы продуктов. Такой темп мы достигаем благодаря переиспользованию 95% текста между различными лицензионными соглашениями с конечными пользователями, а также налаженным процессам подготовки, вычитки и публикации контента – подробнее об этом см. в последующих пунктах статьи.
Регулярные проверки контента
Любой контент, независимо от того, кто его создал, требуется проверять. Регулярные проверки — это ключевой элемент любой зрелой системы управления контентом.Они нужны не «по привычке», а для того, чтобы документационная база оставалась точной и актуальной.
Окончательная редакция текста — это не просто исправленные запятые, а готовый к публикации материал, который грамотно написан, легко читается и приносит пользу аудитории. Чтобы обеспечить постоянное качество контента, рекомендуем выстроить следующий процесс:
Разработайте стиль документации и придерживайтесь его в дальнейшем, создайте централизованную базу знаний команды.
Настройте автопроверки (проверка структуры,терминологии, соответствие шаблонам и т. д.). Они помогают улавливать простые ошибки, снизить нагрузку на редактора и подстраховать его.
Организуйте автоматические воркфлоу для вычитки: автор передает материал на редактуру одним кликом, а система фиксирует статус (на проверке, требует доработки, одобрено).
Собирайте и анализируйте метрики вычитки — процент вычитанного контента, среднее время прохождения воркфлоу, количество правок по типам. Эти данные позволяют увидеть «узкие места». Так, например, если у технического писателя часто появляются стилистические ошибки — ему нужно повторно изучить корпоративный стайлгайд. Если тексты одного автора требуют более 3‑х вычиток — ему нужно чаще использовать автопроверки и привлекать к вычитке ИИ до передачи на ревью.
Эти задачи информационной архитектуры существенно выходят за рамки обычных обязанностей ведущих технических писателей.
Именно роль архитектора контента объединяет редакционное мышление, проектирование пользовательских сценариев, работу с данными и системное проектирование.
В нашем случае качественный контент и переиспользование позволяют сократить время локализации на 35—50 % и выпускать продукты в релиз сразу с пакетом документов на нескольких языках.
Настройка публикации
Контент — это не только написанный текст, но и способ его доставки пользователю. Лейауты маркетинговых и технических материалов должны отличаться: у них разные цели, аудитория и требования к структуре, поэтому каждый тип контента нуждается в своем подходе к публикации. Не создавайте контент «с нуля» для каждого канала. После написания основной версии материала «переодевайте» его в нужный формат согласно выбранному лейауту и правилам доставки. Это позволит вам быстро выпускать один и тот же текст без повторных усилий.
Что необходимо сделать:
Для каждого типа материалов подготовьте соответствующие лейауты (например, для публикации в форматах PDF, HTML, DOCX, MD, JSON, PPTX, TXT и т. д.).
Предусмотрите возможность обновления фирменного стиля — изменения фирменных цветов, шрифтов и прочих визуальных элементов — например, в рамках плановых ребрендингов, которые бывают у нас раз в 3—4 года.
При необходимости определите расписание автоматических публикаций (ежедневно, раз в неделю, по событию) и задайте правила триггеров, которые будут запускать процесс публикации.
Эти задачи обычно возлагаются на архитектора контента, который отслеживает все проекты и учитывает нюансы при формулировании требований к предстоящим изменениям шаблонов и макетов публикации.
Возможность публикации одного и того же контента на справочный портал, в виде встроенной справки в продукт, а также в формате DOCX для передачи на сертификацию и в PDF для передачи партнерам, позволяет нам сократить время подготовки релиза на 20—30%, например на продуктах MaxPatrol SIEM, MaxPatrol EDR, PT Sandbox, PT NAD и PT AF PRO.
Управление жизненным циклом контента
После того как контент опубликован, работа над ним не останавливается. Он начинает обслуживать реальных пользователей, а команда — следить за его жизнеспособностью.
Жизненный цикл контента — это систематический процесс управления контентом, охватывающий все стадии (планирование, создание, контроль, публикацию, продвижение, анализ эффективности и актуализацию, вплоть до окончательного архивирования или удаления). Для полноценного управления контентом внедрите перечисленные ниже практики:
Продумывайте таксономию и модели классификации независимо от конкретной системы документирования. Архитектура контента должна быть такой, чтобы вы в любой момент могли поменять инструмент.
Закладывайте в метаданные атрибуты жизненного цикла: дата создания, дата последней проверки и ответственный за контент и публикацию. Это упрощает отслеживание статуса и планирование обновлений.
Если ваш контент размещен на порталах, собирайте данные о посещаемости страниц и анализируйте поведение пользователей. Эти метрики позволят планировать будущие реструктуризации.
Периодически проводите проверку базы на наличие неработающих ссылок, устаревших фрагментов и дублей. Очистка от лишнего повышает качество поиска и уменьшает нагрузку на систему.
Настраивайте автоматические уведомления, которые будут оповещать о разрыве связей между фрагментами, об устаревании или о необходимости архивации. Это помогает своевременно реагировать на изменения без ручного контроля.
Системный подход обеспечивает актуальность, доступность и целостность корпоративной документации на протяжении всего ее времени жизни.
Мы ежемесячно запускаем минимум 5 автоматических процессов проверки базы, а ежеквартально — проводим аудит качества и уровня переиспользования контента. Эта автоматизация невозможна без архитектора контента, глубоко погруженного в процессы и активно участвующего в разработке и внедрении технологий и систем документирования.
Выводы
Чтобы реализовать все перечисленные рекомендации к построению корпоративной системы документирования, в команде нужен архитектор контента. Одних навыков технического писателя уже недостаточно. Основное различие между ними заключается в масштабе работ и ответственности: архитектор контента проектирует структуру, систему и жизненный цикл документации, тогда как технический писатель фокусируется на создании непосредственно самого контента. Когда эти люди работают слаженно и эффективно, выгоду получают пользователи документации — контент появляется в нужный момент, выглядит единообразно, а значит, он становится предсказуемым и понятным.