Working software over comprehensive documentation…
while there is value in the items on the right,
we value the items on the left more.

[Agile Manifesto, 1:2]

Привет! Меня зовут Андрей Гладилин, я работаю в Swordfish Security над составлением технической документации для ИТ-решений. Нравится нам это или нет, но она сопровождает каждый этап разработки и эксплуатации ПО. Работая над десятками и сотнями описаний ежедневно, я отметил ряд особенностей и сделал полезные выводы. И здесь постарался разобрать все ключевые аспекты, влияющие на качество технической документации, и дать практические рекомендации по его повышению. Этот материал поможет техническим писателям, менеджерам и разработчикам создать документацию, которая точно будет работать.

Для чего нужна техническая документация

Для начала давайте определимся с задачами, которые решает техническая документация в контексте разработки ИТ-решений. 

• Обеспечение коммуникации. Передает техническую информацию и детали проекта менеджерам, разработчикам, тестировщикам, клиентам и т. д. Помогает всем заинтересованным сторонам понять цели, требования, архитектуру, дизайн, способы реализации и другие аспекты проекта.

• Обмен знаниями. Фиксирует знания и позволяет обмениваться ими как внутри проектной команды, так и за ее пределами. Зачастую выступает отправной точкой для дальнейшего развития и помогает при сопровождении решений.

• Обеспечение соответствия требованиям. Помогает приводить продукт в соответствие с юридическими, регуляторными и прочими требованиями. Упрощает реализацию аудитов, сертификаций и других оценочных процедур.

• Обеспечение качества. Позволяет разрабатывать продукт в соответствии с установленными стандартами качества.

• Управление рисками. Помогает выявлять и при необходимости снижать проектные риски. Используется для документирования принятых решений, предположений и компромиссов, которые могут представлять интерес для реализации будущих проектов.

Если всё сделать правильно, то результаты проектов будут радовать гораздо больше, а команда будет получать новые знания и развиваться. Ведь ведущая роль в коммуникации в бизнесе отводится именно документации. Почему так? 

По инициативности принято выделять три вида коммуникаций:

• активные: переговоры, телефонные звонки, видеоконференции, чаты и т. д.;

• интерактивные: электронная почта, форумы и т. п.;

• пассивные: печатные издания и т. д.

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

Но для того, чтобы всё эффективно работало, важно постоянно поддерживать качественную информацию в актуальном состоянии. Например, специалист технической поддержки легко может переадресовать клиента в нужный раздел документации, но если он содержит устаревшие данные, решение вопроса затянется, может потребоваться эскалация на специалистов второй линии. И это повлечет дополнительные расходы. Если пользователь не решит проблему с помощью документации и обратится в техническую поддержку, к затратам на создание низкокачественной документации добавятся расходы на работу after sales специалистов, что в масштабах многомиллионной аудитории может конвертироваться во внушительные бюджеты, ну и отчасти в репутационные издержки. Документация — это всегда «про деньги».

Еще один важный пункт — надежность передачи информации. У пассивных каналов она часто выше, чем у активных, например в разговоре проще упустить детали и в целом невозможно подтвердить факт обмена информацией. Стоимость ошибки в финансовой сфере или атомной энергетике может быть впечатляющей. 

Виды технической документации при продуктовой разработке

В процессе разработки программных продуктов выпускается много технических документов. Каждый из них несет свою функциональную нагрузку и предназначается для разных пользователей:

• Технические задания (спецификации) описывают требования к продукту в части функциональности, производительности, безопасности, масштабируемости и т. д.

• Проектная документация представляет архитектуру и дизайн-решения, включая диаграммы и схемы, описания и характер взаимодействия компонентов, а также другие технические аспекты решения.

• Пользовательская документация содержит информацию по эксплуатации продукта, в том числе по установке, настройке, запуску, использованию, резервному копированию, отладке, описанию интерфейсов и т. д.

• Тестовая документация включает в себя методики, планы, сценарии и результаты испытаний.

• Документация по безопасности описывает способы защиты информации и управления рисками, в том числе рекомендации по обеспечению защищенности, стандарты, процедуры, политики и др.

• Обучающие и информационные материалы предоставляют ценные сведения всем заинтересованным сторонам. 

Современные подходы к разработке технической документации

От качества технической документации в значительной мере зависит то, насколько успешным будет продукт и как пользователи будут воспринимать его (в англоязычных источниках это называется User eXperience, UX). Поэтому при создании документации важно уделять достаточное внимание способам формирования, оформления, распространения и т. д.

В современной разработке технической документации всё большую популярность приобретают следующие принципы и подходы:

Использование единого источника. В рамках этого подхода данные собираются в одном формате и помещаются в общее хранилище. Среди преимуществ:

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

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

• сопровождение существенно упрощается.

DocOps. В основе этого подхода — лучшие практики, процессы и инструменты, которые успешно используются при создании программного обеспечения. Он позволяет в значительной мере автоматизировать разработку, публикацию и сопровождение технической документации — это повышает ее качество и сокращает затраты. Логичным продолжением подхода является его прикладная реализация — Doc-as-code — работа с документацией как с программным кодом. Более подробно об этом ниже.

Минимализм. Этот принцип предусматривает использование ясного и краткого языка, облегчающего чтение и восприятие. Можно фокусироваться на необходимом без излишней детализации. Современного пользователя мало интересует подробное описание основных элементов интерфейса, например, поэтому стоит отдавать предпочтение только востребованным сценариям и пошаговым инструкциям, которым легко следовать.

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

Использование графических, видео- и интерактивных материалов. Эти элементы делают документацию более информативной и увлекательной. Взаимодействие с продуктом непосредственно из документации (и наоборот), видеоинструкции, чат-боты, интерактивные элементы и т. д. — всё это сегодня широко распространено. Здесь важно не переусердствовать. Например, не стоит иллюстрировать скриншотами каждый шаг руководства, ведь зачастую при работе с документацией интерфейс продукта уже и так находится перед глазами пользователя. 

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

Синхронизация разработки продукта и пользовательской документации. Обеспечивается административной поддержкой и реализуется на прикладном уровне. Взаимное «наложение» процессов, особенно в рамках DocOps-парадигмы, позволяет максимально синхронизировать выпуск сопроводительной документации с релизными циклами продукта.

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

Формирование культуры документирования

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

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

• Точность. Фактическая достоверность и актуальность информации, отсутствие ошибок.

• Ясность. Четкая структура, простой стиль изложения, лаконичность. Полезные инструкции, понятные примеры, наглядные графические материалы.

• Полнота. Охват всех необходимых аспектов продукта в разрезе функциональных возможностей и потенциальных сценариев использования.

• Согласованность. Стиль, тон, терминология и оформление — всё должно согласовываться в рамках материала и соответствовать назначению документа.

• Удобство использования. Предельно ясная организация материалов, качественная навигация, возможность сквозного поиска по документам.

• Релевантность. Максимальное соответствие запросам заинтересованных сторон, ответы на поставленные вопросы, помощь в решении проблем.

• Технологичность. Простота сопровождения и обновления.

А теперь поговорим о процессах документирования — с ними всё сложнее. Несмотря на то, что они не относятся к критически важным, их успешное внедрение играет заметную роль и однозначно отражает общий уровень зрелости проектной команды. Разработка технической документации требует привлечения широкого круга специалистов — это весьма трудозатратно и дорого, поэтому процесс должен быть качественным.

Отметим наиболее очевидные преимущества внедрения и формализации процессов создания технической документации:

• Повышение качества разработки. Вся необходимая информация передается в полном объеме. Правильно выстроенные процессы разработки помогают предотвратить потерю данных и уменьшить количество ошибок разного характера.

• Повышение производительности. Отлаженные процессы позволяют снизить издержки на разработку документации.

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

• Повышение результативности совместной работы. Эффективные проектные коммуникации, уменьшение количества недопониманий и конфликтов, а также повышение продуктивности — вот лишь небольшой перечень бесспорных плюсов.

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

Ключом к успешному распространению культуры документирования являются искренняя заинтересованность в этом основных стейкхолдеров и высокое качество командных коммуникаций. Хороший процесс не может не родить результат (с).

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

Жизненный цикл разработки технической документации

• Планирование. Формируются состав и объем документов, разрабатываются требования, определяются сроки и критерии качества. В идеале здесь участвуют все заинтересованные стороны, обменивающиеся информацией, и, конечно, специалисты по технической документации.

• Сбор информации. Изучаются, анализируются и систематизируются необходимые сведения. Это выполняют специалисты по технической документации, также привлекается широкий круг профильных экспертов.

• Проектирование. Разрабатывается общая структура, определяется содержание документов, устанавливаются требования к оформлению. Этим занимаются специалисты по технической документации, на этапе согласования могут привлекаться другие заинтересованные стороны.

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

• Редактирование. Документы редактируются на предмет грамматических и стилистических ошибок. Проверяется соблюдение единства используемой терминологии и общая согласованность документа. Обычно задачи перекрестно выполняются техническими писателями (в отдельных случаях — редактором), привлечение других специалистов не обязательно, но приветствуется. Этап завершается тестовой публикацией.

• Ревью. Эксперты и другие заинтересованные стороны изучают, проверяют на соответствие критериям качества и утверждают документы.

• Публикация. Документы размещаются в оговоренных форматах и передаются заказчику.

• Приемка. Проводится работа с замечаниями внутреннего или внешнего заказчика, вносятся правки.

• Сопровождение (поддержка). По мере развития продукта документация улучшается и обновляется.

• Мониторинг. Проверяется и анализируется широкий спектр параметров: начиная от состояния сервера, на котором опубликована документация, и заканчивая оценкой посещаемости и качеством контента.

С учетом различных особенностей проекта и команды, а также множества других факторов отдельные этапы могут трансформироваться, пропускаться и/или объединяться. Однако при детальном их рассмотрении можно заметить сильное сходство цикла разработки документации с циклом разработки программного обеспечения. Более того, при придании процессу циклического и итеративного характера мы вплотную приближаемся к DevOps-модели с поправкой на функциональное наполнение этапов. Очевидно поэтому в последние годы в отношении подобного подхода всё чаще применяется термин DocOps.

DocOps

Одна из основных идей DocOps заключается в том, что создание технической документации осуществляется в тесном контакте с разработкой программного продукта и во многом «отзеркаливает» последнюю. Сотрудники, занимающиеся формированием документации, тесно интегрируются в продуктовую команду, процессы максимально синхронизируются и объединяются в общую систему.

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

Логичным продолжением DocOps-парадигмы является ее инструментальное воплощение, получившее название Doc-as-сode (документация как код).

Doc-as-code — это прикладная реализация разработки и сопровождения технической документации, в рамках которой применяются инструменты для работы с программным кодом. Исходные документы хранятся в системе контроля версий, для их форматирования используется один из легковесных языков разметки.

Среди преимуществ DocOps можно отметить следующие:

• повышение технологичности разработки — увеличение скорости (снижение time-to-market) и упрощение сопровождения;

• повышение эффективности взаимодействия команды;

• широкие возможности автоматизации — максимальное устранение рутинных операций;

• обеспечение «прозрачности» процесса документирования;

• упрощение организации и контроля командной работы;

• плотная интеграция с процессами продуктовой разработки;

• эффективное использование ресурсов;

• использование привычного для большинства членов проектной команды инструментария.

Несмотря на всё это, у DocOps есть и недостатки:

• высокая стоимость внедрения: развертывание и настройка системы документирования не самые тривиальные задачи, их решение требует ощутимых временных затрат и предъявляет довольно высокие требования к исполнителям;

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

• необходимость скоординированных и согласованных действий всех участников процесса;

• ощутимый порог входа для технических писателей, привыкших работать в WYSIWYG-редакторах.

Взглянем на основные этапы разработки технической документации сквозь призму DocOps и Doc-as-Code.

Как уже отмечалось, для создания исходных документов используется один из легковесных языков разметки, например Markdown. Такие языки позволяют довольно просто размечать текстовые документы, читать и редактировать их без применения специальных инструментов (подойдет любой текстовый редактор), а также однозначно автоматически конвертировать их различные публикуемые форматы, например HTML, PDF, Docx.

Хранение исходных материалов осуществляется в системе контроля версий, например Git. Это открывает широкие возможности по версионированию, ветвлению, отслеживанию изменений, трассировке задач и т. д. Также использование системы контроля версий облегчает автоматизацию процессов, например тестирования и публикации. Больше не нужно думать об оформлении документов — акцент делается на содержании.

Открытие Pull request в системе контроля версий — сигнал для начала ревью. Современные инструменты (GitHub или GitLab) предлагают богатый инструментарий для проведения ревью и совместной работы. Одобрение Pull request — переход к публикации. Сам же процесс публикации удается полностью автоматизировать.

Поскольку для разработки и публикации используется привычный инструментарий, эксплуатация обычно не вызывает сложностей при поддержке со стороны DevOps-инженеров. Задача команды документирования на этом этапе сводится к мониторингу.

Данная статья содержит, главным образом, теорию. В следующем материале будет практика. Подробно разберем пример реализации DocOps-подхода, который «закроет», пожалуй, 80% задач, стоящих перед среднестатистической командой технических писателей при разработке сопроводительной документации продукта.

До новых встреч, друзья!