Порядок против хаоса: как не проиграть в битве за понятную документацию?

Документацию не читают? Увы, но это действительно так. Достаточно вспомнить своё типичное поведение при покупке нового прибора: сначала включим в сеть, а уже когда не заработает, прочтём инструкцию.
Давайте вместе разберёмся, почему так происходит и что с этим делать.
Я — Мария Киселёва, начальник отдела разработки технической документации в РТЛабс. 12 лет в технической документации научили меня, что хороший текст начинается не с красивых слов, а с жёстких договорённостей. Глоссарии, стайлгайды, шаблоны и отказ от двусмысленности — без этого любая инструкция превращается в «письмо из Простоквашино»: то лапы ломит, то хвост отваливается :)

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

Документацию не читают

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

Когда документация непонятна – она бесполезна, а значит, не выполняет свою цель. «Если ничего не помогает, прочтите, наконец, инструкцию», – часто повторял мой преподаватель в институте. Будучи неопытной студенткой, тогда я воспринимала эти слова как «мне угрожают чтением документации». Проработав более 12 лет техническим писателем, теперь каждый раз, когда моя инструкция или документ помогли или сэкономили время своему читателю, я чувствую принесённую пользу и понимаю, что хорошая документация — это благо. Качественная инструкция, руководство или описание способны стать источником знаний для пользователя и здорово сэкономить его время и силы на поиск ответа. Неудобная и непонятная документация может вызвать обратный эффект: читатель теряется и путается, в его голове прогрессируют хаос и неопределённость. Одного такого негативного опыта достаточно, чтобы пользователь начал воспринимать любой документ как источник стресса и избегать его чтения.

Технический текст и эмпатия

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

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

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

Читатели документации – кто они

В парадигме документации целевая аудитория и цель документа связаны напрямую: цель документа достигнута, когда он решает запрос целевой аудитории.

Другими словами, документация не может существовать в отрыве от читателя. И чтобы говорить на одном языке с ним, при создании документа важно понять:

— для кого предназначен документ;

— запрос, цель или проблему, с которыми читатель обратился к документу.

И затем отразить это в тексте.

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

— внешняя — предназначена для внешних пользователей;

— внутренняя — для использования на проекте, в компании или в команде.

Заказчиками документации выступают, соответственно, внешние и внутренние пользователи. И даже сам автор документа может являться заказчиком, если у него возникла потребность задокументировать своё знание или знание эксперта.

В зависимости от категории пользователей будут отличаться и виды документации и ИТ-контента:

— пользовательская и эксплуатационная документация для внешних потребителей контента. Например, это API-документация, руководства/мануалы, отчётная ГОСТ- и другая документация;

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

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

Но никакой, даже самый хороший документ, не существует в вакууме. Он элемент системы.

Документов много ‒ документация одна

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

С точки зрения архитектуры программное обеспечение похоже на «сэндвич» из разных слоёв: начиная от того, как организованы данные, и заканчивая тем, как выглядит пользовательский интерфейс (при наличии пользователя). Для каждого уровня предусмотрен свой вид документа и на этапе проектирования и разработки, и на этапе эксплуатации продукта.

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

Так как программные и технические продукты обычно развиваются, то и документация должна развиваться вместе с ними. Если смотреть глобально, то документация – это элемент информационной системы, а документ — это элемент документации (системы документации). Изменения в одном элементе неизбежно влияют на другие элементы и на всю систему.

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

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

Контекст управляет качеством

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

Если рассмотреть отдельную продуктовую команду или отдельный проект, в котором живёт документация разных стадий разработки продукта, то задача свести все изменения воедино и получить на выходе качественный документ (или комплект документации) кажется невыполнимой. Плюс нужно учитывать, что у каждого автора свои стиль изложение и видение «как лучше написать». Авторы часто работают в замкнутом информационном поле и не чувствуют общего контекста. В результате документация в комплекте получается разрозненной и чем-то напоминает знаменитое «письмо из Простоквашино».

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

Но если просто неопрятный, разрозненный и разностилевой в плане оформления документ ещё как-то можно прочитать (хоть и с трудом!), то гораздо больше проблем вызывает непонимание автором контекста.

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

Что это значит: недостаточно бесшовно вписать изменение в окружающий текст, важно при этом не исказить весь смысл.

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

Единого контекста в документации можно добиться, соблюдая стандартные критерии качества при работе с техническим текстом:

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

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

3. полнота — покрытие описаниями всех функций. Критерий соблюдается, если документация включает описания всех необходимых функций, к которым предъявлялись требования на этапе проектирования, и эти описания достаточны для понимания целевой аудиторией;

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

Рассмотрим критерии более детально. Я поделюсь своим опытом и реальными примерами, как при оформлении документации достичь максимального соответствия этим критериям.

Консистентность против хаоса в документации

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

1. Стили и шаблоны

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

В соответствии с ГОСТ требования к документации меняются в зависимости от стадии разработки продукта. Не важно, идёт речь о программном обеспечении и ГОСТ серии 19 или автоматизированных системах и ГОСТ серии 34.

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

Примеры того, как эти требования выглядят в документации, смотрите на рисунках ниже.

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

2. Элементы интерфейса

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

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

Разнообразие элементов интерфейса и их названий запутывают и авторов контента, и читателя. В большинстве случаев достаточно объединить все схожие элементы в одну сущность. Например, всё, что кликабельно и нажимается, — это «кнопка», а всё, что переключается, − «переключатель». Потому что пользователю в принципе не столь важно, какой вид кнопки он нажимает: «кебаб»-кнопку, радиокнопку или текстовую кнопку. Важно то, какое действие он совершает, чтобы получить результат.

3. Термины и сокращения

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

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

Для работы с терминами я выработала несколько полезных правил:

1. Термины и их определения в документации не должны противоречить ТЗ и НПА, если работы опираются на формальные акты и регламентируются ТЗ.

2. Если термина и определения в ТЗ нет, можно воспользоваться ИТ-словарём (он же ГОСТ 33707—2016) или другими открытыми проверенными источниками, например официальными справочными ресурсами, методическими материалами, регламентами и документацией по заданной тематике.

3. При вводе нового термина его определение при возможности нужно унифицировать:

   — упростить тяжёлые для восприятия словесные обороты;

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

   — минимизировать терминологическую вложенность, которая усложняет работу с глоссарием.

   Терминологическая вложенность – это когда определение термина содержит другой термин, который так же требует внесения в глоссарий

4. Если термин используется только в разрезе определённого продукта, документа или проекта и употребляется локально, но при этом у него есть общепринятое определение, нужно вводить отдельный проектный глоссарий или помечать такой термин в общем глоссарии, чтобы его локальное определение не было ошибочно растиражировано за пределы частных случаев употребления

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

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

4. Употребление терминов

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

Киллерфича таких инструкций — сопровождать правила примерами правильного и неправильного употребления терминов. Такая «шпаргалка» экономит время команды на подготовку контента и служит авторитетным источником, к которому всегда можно обратиться, если есть сомнения в написании формулировки или термина.

На рисунке ниже – небольшой фрагмент гайда, который мы используем в команде.

Непротиворечивость против хаоса в документации

Если консистентность – это больше про оформительскую корректность, логистику контента и его визуальную составляющую, то непротиворечивость напрямую связана с фактологией текста.

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

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

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

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

Для согласованности информации можно использовать шаблоны типовых описаний функциональности — так называемые фигуры описания (подробнее о них можно прочитать в книге «Разработка документации пользователя программного продукта» Кагарлицкого Ю. В.).

Например, когда описываются интеграции и детализируются параметры запросов к REST API, технические описания легко «загоняются» в типовую форму → на выходе материалы от разных авторов получаются стандартизированными и совместимыми друг с другом.

Еще одна «киллерфича» такого подхода — описания получаются достаточными, полными и не противоречат друг другу по сути.

Полнота против хаоса в документации

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

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

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

Поделюсь своими идеями, как организовать сбор и анализ обратной связи:

— коммуникация с первой линией поддержки, которая собирает обращения внешних пользователей по вашему продукту;

— коммуникация с продуктовой командой по статьям локальной базы знаний через форму обратной связи, поле для комментария, встроенные комментарии или «лайк/дизлайк» на странице — в любой популярной Вики-системе есть такие возможности.

— коммуникация с бизнесом и заказчиком, которую обычно ведут менеджеры или владельцы продукта, — они могут указать на недостатки в документации с точки зрения соответствия бизнес-требованиям и адаптации под целевую аудиторию.

Однозначность против хаоса в документации

Техническая документация не терпит двусмысленности, её текст должен исключать варианты различных интерпретаций или неправильного толкования. За время своего опыта я накопила список таких «красных флагов» и «узких мест» документации и собрала их в наглядную таблицу.

Приведу ещё один жизненный пример для последнего пункта: когда термин используется одновременно в широком и узком значении. Например, SDK. В широком контексте — это аббревиатура с общепринятым значением «software development kit». В узком контексте это может быть локально введённый термин для сокращения названия конкретного SDK: чтобы уместить его на схемах или не перегружать сложносочинённый текст длинными названиями. При вводе такого локального термина следует взвешивать все за и против, так как последующее его применение потребует особой внимательности и знания контекста как от автора, так и от ревьювера. Иначе есть риск использования такого локального термина в неподходящем контексте, из-за чего могут возникнуть нестыковки в тексте и вызвать у читателя конфликт понятий.

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

Использование инструкций – новая привычка

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

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

1. качество и пользу инструкций;

2. удобство их использования.

Если тестирование прошло успешно, можно начинать делиться инструкциями с пишущими коллегами, масштабировать на команду. Тут важно помнить, что само ничего не будет работать, и процесс нужно постоянно онбордить: проводить встречи, знакомить коллег с материалами, объяснять их ценность и регулярно о них напоминать, давать развитие этой активности и быть готовым к обратной связи. Всегда отлично работают на таких тематических встречах истории с «до» и «после»: живые примеры всегда дают хороший отклик.

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

Даже если кто-то из команды не согласен с термином в глоссарии, принятой фигурой описания или новым правилом – это отличный повод собрать встречу, обсудить варианты, послушать разные мнения и выработать компромиссное решение. Если случай совсем нестандартный, тогда точно нужно договариваться сообща и фиксировать эту договорённость как новое правило.

Надеюсь, что описанные в этой статье приёмы и наш опыт помогут побороть хаос в вашей документации или предотвратить его при работе с контентом. Единый контекст, чёткие критерии качества и централизованные своды правил:

— повышают качество документации и, как следствие, конечного продукта;

— экономят время команды — не нужно заново договариваться и тратить ресурсы на споры и выработку решений;

— выступают согласованными авторитетным источником – если всё-таки поспорить хочется, а договориться не получается;

— помогают команде коммуницировать эффективнее — договорённости зафиксированы, а документация понимается всеми одинаково;

— снижают когнитивную нагрузку на мозг, потому что под рукой всегда есть легитимная шпаргалка, к которой можно и нужно обращаться.

Пишите свои вопросы и предложения в комментариях, буду рада на них ответить.