• «Ваша документация — отстой!»

• «Я её никогда не читаю, всё равно там всякая ерунда написана!»

• «Да любая нейросеть быстро напишет это в сто раз лучше»

• «Там никогда не найти ничего нужного»

• «Документаторы опять всё напутали»

• И классика: «А разве у нас есть документация?»...

Обратная связь от читателей-пользователей далеко не всегда бывает конструктивной и вдохновляющей.

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

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

1. «В документах невозможно ничего найти»

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

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

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

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

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

Как исправить:

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

• Предусмотреть механизм глобального поиска по всем документам.

• Не забывать добавлять перекрёстные ссылки между разделами.

2. «Ваша документация бесполезна»

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

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

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

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

Как исправить:

• Ориентироваться на конкретные потребности целевой аудитории.

• Сформулировать основные сценарии использования документации.

• Избегать формального подхода, сообщать читателям нужные подробности.

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

3. «В документации в разных местах написано по-разному»

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

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

Есть ещё вариант: каждое из описаний верно в контексте определённого раздела, но эта особенность никак не отражена в документе. В любом случае читатель получает возможность поиграть в увлекательную игру «Угадайка».

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

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

Как исправить:

• Использовать технологию единого источника.

• Избегать повторов описания в разных разделах — использовать ссылки на единственный раздел.

4. «В документации всё устарело»

Да что уж там говорить, писатели не всегда успевают подогнать документацию под бодрый темп релизов систем. Бывает, что выпуск документов запаздывает. Конечно, это не нравится читателям. Идеальным вариантом было бы всегда успевать выпускать документацию вовремя. Но на пути к светлому идеалу всегда можно принять превентивные меры.

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

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

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

Как исправить:

• Чётко указывать атрибуты актуальности каждого блока информации.

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

• Организовать процесс транслирования всех изменений писателям.

5. «Да там сплошные ошибки»

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

Бывают и другие ошибки. Авторы, например, могли:

• просто не получить важную информацию (этот случай мы уже рассматривали);

• опираться на устаревшие источники информации;

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

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

• неправильно понять то, что нечётко изложено в источниках.

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

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

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

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

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

Как исправить:

• Организовать процесс проверки документации.

• Уточнять актуальность и полноту источников информации.

• Всегда опираться на источники информации.

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

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