К теории качества документации

Diátaxis — это подход к качеству документации.

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

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

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

Функциональное качество

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

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

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

Что ещё усложняет задачу автора: любое несоответствие этим требованиям сразу заметно пользователю.

Глубинное качество

Есть и другие свойства — назовём их глубинным качеством.

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

Например:

• ею приятно пользоваться

• плавность

• соответствие человеческим потребностям

• красота

• предвосхищение потребностей пользователя

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

Это свойства глубинного качества.

В чём разница?

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

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

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

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

Функциональное качество объективно — оно относится к внешнему миру. Достоверность документации определяется тем, насколько она соответствует реальности, которую описывает. Глубинное качество нельзя установить простым сопоставлением с реальностью. Оно субъективно: оценивать его можно только через потребности человека, который воспринимает документацию.

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

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

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

Как распознать глубинное качество

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

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

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

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

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

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

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

Diátaxis и качество

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

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

Выявление изъянов функционального качества

Хотя Diátaxis не может сам по себе обеспечить функциональное качество, подход всё же помогает его поддерживать.

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

Например, Diátaxis рекомендует, чтобы архитектура справочной документации отражала архитектуру документируемого кода. Благодаря этому пробелы в документации становятся гораздо заметнее.

Другой пример: когда из учебного руководства согласно принципам Diátaxis убирают пространные объяснения, часто обнаруживается участок, где читателя оставили разбираться самостоятельно.

Но применительно к функциональному качеству принципы Diátaxis могут играть лишь аналитическую роль.

Создание глубинного качества

В отношении глубинного качества Diátaxis способен на большее.

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

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

Кроме того, Diátaxis напрямую работает с плавностью. Плавным — в документации или где угодно ещё — ощущается естественный, непринуждённый переход от одного этапа или состояния к другому, согласованный и с нашей текущей целью, и с тем, как в целом работают наши разум и тело.

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

И так далее.

Понимание ограничений

Важно понимать: Diátaxis никогда не даст всего, что требуется для достижения глубинного качества.

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

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

Использование Diátaxis не гарантирует глубинного качества. Его свойства постоянно переопределяются, переосмысливаются, заново открываются и изобретаются. Но Diátaxis может создать некоторые условия для самой возможности глубинного качества документации.