Привет, Хабр. Ранее я писала о том, как мы внедряли корпоративную систему управления контентом, с помощью которой удалось объединить более 200 сотрудников из разных департаментов. В этот раз расскажу непосредственно о процессе техдокументирования. Несмотря на то что этой теме посвящено множество статей, живых примеров «эволюции» технической документации я еще не встречала. Наверное, стоит это исправить ????. Сегодня я покажу путь развития технической документации с нуля на примере PT Application Firewall и поделюсь инструментами, которые помогают нам ее делать.

С чего все начиналось

Летом 2013 года, когда я только пришла в Positive Technologies на должность ведущего технического писателя, документации для межсетевого экрана уровня веб-приложений PT Application Firewall еще не существовало. Департамент информационной поддержки в то время готовил техническую документацию только для двух продуктов в линейке компании. Справка для продуктов создавалась в Help & Manual (позднее в Adobe RoboHelp), а все прочие документы — в Adobe FrameMaker или Microsoft Word.

Наброски руководства представляли из себя небольшой PDF-файл. Каждый автор писал в собственном стиле, поэтому использовать контент повторно не всегда получалось. Иногда процесс заимствования текста другого автора, особенно из другого департамента, усложнялся тем, что нам не удавалось быстро найти исходники контента. Также на тот момент у нас еще не было устоявшейся процедуры вычитки документации и четко сформулированного стайлгайда. Именно тогда идея о внедрении корпоративной системы управления контентом, давно зародившаяся в компании, получила толчок к реализации.

Первые шаги

В октябре 2013 года мы написали первый документ для PT Application Firewall (кстати, в нем можно увидеть скриншоты ранних версий продукта!). Руководство администратора было совсем маленьким — всего пару разделов на девять страниц. Стенда, на котором мы могли бы тестировать и изучать ПО, у нас не было, поэтому работали, как говорят летчики, «по приборам»: переработали информацию от департаментов анализа защищенности и маркетинга, а затем заверстали в корпоративном стиле.

Осенью 2014 года, когда у нас появился доступ к стенду, а к разработке документации подключился один из наших инженеров, мы создали еще три документа: руководство по установке на модуль Cisco, краткое руководство по установке на модуль Cisco и руководство пользователя.

Постепенно PT Application Firewall обрастал функциональностью, и мы расширяли документацию. Частичное переиспользование в гайде обучающего курса по продукту позволило нам покрыть описаниями большую часть системных объектов. В начале 2015 года один из документов выглядел уже весьма основательно.

Хотя с момента появления первого документа прошел целый год, процесс документирования все еще не был налажен: мы урывками получали информацию по почте, были оторваны от процесса разработки продукта, не имели закрепленного за нами стенда с продуктом и не вели список задач в трекере. Кроме того, мы понимали, что стиль нашей документации устарел. Нам требовалось обновить дизайн (макет страниц, шрифты, стиль абзацев и символьные стили). С этим нам помогли ребята из креативного отдела. Они подготовили эскизы страниц и дали рекомендации по настройке лейаута.

От хаотичности и обособленности к общей рабочей среде

В 2015 году наша команда писателей начала разрастаться. Серверного ПО для разработки документации у нас пока не было, поэтому каждый работал изолированно, дотачивая стили и шаблоны документации индивидуально под свои проекты. Большая часть исходников хранилась на личных дисках, и единые требования к хранению готовых PDF-файлов мы тогда еще не сформировали. Чтобы не писать параллельно один и тот же текст для разных продуктов, требовалось синхронизировать задачи.

В следующем году произошло важное событие в жизни документации PT Application Firewall: мы перенесли и стали поддерживать ее в системе управления контентом SCHEMA ST4 (подробнее об этом я рассказывала в прошлой статье). Это позволило нам:

• сократить время на подготовку документов за счет повторного использования ранее написанных разделов документов или отдельных параграфов;

• сократить расходы на повторную редактуру и локализацию за счет переиспользования общих разделов;

• верстать все документы в едином стиле;

• исключить структурные, стилевые и пунктуационные ошибки, которые SCHEMA ST4 может находить автоматически (например, в руководстве администратора благодаря этим проверкам на тот момент было исправлено около 500 технических ошибок).

Переход в SCHEMA ST4 случился благодаря приходу в компанию директора по продуктовым сервисам с огромным опытом в области документирования и локализации. Она проанализировала наши процессы и контент и обосновала топ-менеджменту необходимость внедрения новой системы. Параллельно с освоением нового инструмента мы учились по-новому писать документы: на основе подробного стайлгайда и с использованием единообразного подхода к созданию разделов. Это помогло типизировать разделы всех документов и начать одинаково писать инструкции, статьи и вводные разделы. Часть контента (копирайт, описание компании, информацию о работе техподдержки и пр.) мы начали переиспользовать между всеми продуктами.

В начале 2017 года мы выпустили руководство администратора PT Application Firewall, полностью подготовленное в нашей корпоративной CMS. Вскоре все технические писатели стали работать в SCHEMA ST4, и прочий софт нам теперь был не нужен. При необходимости мы могли быстро переключаться между проектами и находить любые исходники.

Как я уже говорила, начиная с 2016 года мы стали менять процессы разработки документации для PT Application Firewall. Например, мы перешли на работу по фичам в трекере TFS, а за каждым продуктом закрепили своего технического писателя, редактора, сервис-менеджера и локализаторов. Последние занимаются переводом документации, приводят в порядок ресурсные строки на английском языке и работают с текстами визардов, которые появились у нас в 3.6.2. Когда английская локаль была вычитана и все захардкоженные строки были перенесены в ресурсные файлы, у продукта появилась русская локаль. Писатель и инженер по локализации теперь были глубоко погружены в проект, и благодаря этому мы еще до передачи новой фичи на документирование знали, какие изменения произошли или запланированы в UI. Так нам удалось снизить количество ошибок, связанных с неактуальными скриншотами и названиями экранных контролов. Примерно в то же время к нашей команде подключились английский редактор и переводчица с корейского. Проверка документации носителями языка позволила нам избежать языковых ошибок.

По мере расширения команды продукта к фактической вычитке в SCHEMA ST4 присоединились разработчики, тестировщики и аналитики. Благодаря этому были исправлены многие фактические ошибки (к 2022 году мы обработали около 3000 комментариев коллег). Вместе мы смогли описать варианты развертывания и варианты производительности системы для разных аппаратных платформ. В релизный комплект вошли руководство администратора, руководство по быстрому старту и Release Notes. Финальные версии релизных документов мы выкладываем на SharePoint, чтобы каждый сотрудник компании мог легко их найти.

Что важно, комплект релизных документов также пополнился документом «Начало работы», в котором описывается развертывание в Microsoft Azure, а руководство администратора версии 3.6.2 уже включало в себя базовое описание REST API. Кроме того, для версии 3.6.3 мы выпустили руководство по использованию удаленного сервера лицензий.

Переиспользование контента между подразделениями

С декабря 2017 года к нам в департамент информационной поддержки стали приходить документы от центра компетенций (ЦК), занимающегося пилотированием продуктов и поддержкой продаж. Например, мы поместили в SCHEMA ST4 политику лицензирования PT Application Firewall, полученную от ЦК, и из этого документа переиспользовали в гайдах описание модулей M-SCAN и P-Code, а также некоторые термины для нашего глоссария. Именно тогда мы начали продумывать возможности хранения контента ЦК в нашей корпоративной системе и строить планы по импорту документов.

В том же году вместе с коллегами из группы системной интеграции мы подготовили первую версию документа про развертывание систем PT Application Firewall на базе унифицированных аппаратных платформ. Сегодня по PT Unified Hardware Chassis, предназначенной для установки продуктов Positive Technologies, на внутреннем портале размещена наша документация, основанная в том числе на этом документе.

Кастомные сборки

К выходу PT Application Firewall 3.6.3 нам прилетела сложная задача: нужно было заверстать под шаблон одного из наших партнеров руководство администратора и заменить там все скриншоты. От нас требовалось поддержать обе версии документа: нашу стандартную в темной теме и в стилях партнера со светлым PT Application Firewall. Для этого мы разработали новый шаблон, а все скриншоты разместили по группам. Из групп по фильтру публикации в PDF попадала нужная нам версия. Так, с апреля 2018 года мы начали поддерживать несколько лейаутов для документов, и этот опыт пригодился нам в будущем. Заодно мы улучшили качество скриншотов, научившись снимать их в Snagit и соблюдая рекомендации наших дизайнеров пользовательских интерфейсов. Все скриншоты были сняты в одинаковом размере, были убраны белые поля и лишние элементы подсветки, текст перестал быть размытым.

Сейчас мы умеем не только создавать новые лейауты, но и в рамках одного лейаута автоматизировать применение нужных нам стилей и макетов страниц.

Другой пример кастомной сборки — сертификация в Казахстане. Благодаря использованию переменных для названий продукта и компании мы смогли быстро подготовить сборку для казахской сертификации в 2018 году. До сих пор мы пользуемся этими наработками, но уже для других наших продуктов.

Брейншторм для улучшения документации

С 2019 года мы стали чаще встречаться с командой проекта, синхронизировать цели и давать друг другу обратную связь. Со всеми участниками проекта (в том числе с ребятами из технической поддержки и из отдела подготовки продаж) мы думали над тем, как улучшить документацию при переходе с версии 3.x.x на 4.x.x. На встречах решили, что надо обогатить документацию описаниями сценариев использования, например, такими как использование прокси-сервера, расшифровка SSL-трафика и настройка IP-адреса для проксирования трафика на защищаемое веб-приложение. Кроме того, мы договорились переписать раздел про развертывания. С этим нам помог руководитель департамента разработки PT Application Firewall, который написал разделы по архитектуре, Kubernetes и внешним агентам, а также подключил дизайнеров, которые создали очень красивые схемы для каждого из вариантов деплоя.

Начать все сначала

Несмотря на то, что в документацию «тройки» было вложено много сил, мы приняли решение переписать в «четверке» все с нуля. И не ошиблись — отзывы наших сотрудников подтверждают, что оно было верным!

Сейчас все разделы документов проходят через стандартные воркфлоу вычитки и перевода. Между документами настроен реюз: процент переиспользования внутри проекта очень высокий — около 80%. Воркфлоу работы по фичам налажен (с этим нам здорово помог менеджер проекта из департамента разработки PT Application Firewall). Релизный комплект документов сегодня состоит из руководства администратора, справочного руководства по REST API, справочного руководства по правилам обработки трафика и Release Notes. Все эти документы выложены в виде справки на корпоративном справочном портале (EULA используется унифицированная). Скоро этот портал станет доступен внешним пользователям.

Дополнительно мы поддерживаем в SCHEMA ST4 такие документы по PT Application Firewall, как спецификация, анкета ТКП, техническое предложение, политика лицензирования, предложение на проведение пилотного проекта и FAQ.

Сейчас для всех продуктов Positive Technologies также есть справка в Git на корпоративном онлайн-портале, которую можно выгрузить в формате JSON. Локальную справку в продукт планируем добавить в одной из следующих версий PT Application Firewall.

Наши задумки

Еще в 2020 году мы начали обсуждать возможность склеивать описания эндпоинтов от разработчиков с основной частью руководства по REST API. Пока интеграция со Swagger у нас не настроена, и мы думаем, как решить эту задачу. Тема интересная, и мы продолжим изучать ее в этом году.

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

Заключение

Принимать активное участие в развитии документации, причем в разных ролях, для меня было очень важно и интересно. Разрабатывать документацию стало легче, и она стала более понятна пользователям наших продуктов. За девять лет мы не только оптимизировали процесс создания документации и повысили ее качество, но и выстроили крепкие и доверительные отношения в команде. Сейчас я руковожу группой архитекторов контента, которые помогают авторам со всех проектов готовить контент в нашей системе документирования, а также продолжаю участвовать в подготовке документов на проекте PT Application Firewall как сервис-менеджер. Своим опытом я делюсь на различных конференциях и внутренних митапах, а еще пишу небольшие статьи во внутреннем блоге, рассказывая о лучших практиках. Я и другие руководители подразделений стремимся, чтобы авторы все больше вовлекались в процесс документирования и выполняли свои задачи не только эффективно, но и с увлечением.