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

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

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

3 аспекта проблемы

Немного об источнике. В сериале Mononoke Аптекарь — загадочный странник, который изгоняет злобных духов (мононоке), но только после того, как поймет их природу. Для этого он должен узнать о духе три вещи:

1. Форма: как дух проявляется, его внешнее воплощение

2. Суть: что дух делает, его поведение или механика

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

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

Метод Mononoke в технической документации

Метод выглядит широким и применимым к множеству специальностей и задач. Разберем, как применить его в нашей профессии. Технические писатели могут иметь разную специализацию, применять различные подходы и методики. Например, я готовлю пользовательские инструкции к платформе для тестирования ПО, руководствуясь подходом topic-based authoring.

В задачи входит написание материалов следующих типов:

1. Task topic — описание процесса, подготовка инструкций. Это самый распространенный тип статей.

2. Concept topic — концептуальная статья, описывающая поведение, назначение, принципы и т.д

3. Reference topic — справочные материалы (например, список вебхуков и их переменных)

4. Release notes — справка о новой / устаревшей функциональности и устраненных дефектах

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

1. Форма — визуальная часть, например UI

2. Суть — процесс, поведение системы, или концепция

3. Причина — назначение или ценность фичи или продукта. С формулировки причины начинается разработка фичи.

1. Форма — визуальная часть, UI

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

Как применять

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

Например, если пиктографика в UI неочевидна, мы выделяем ее на скрине (здесь показан интерфейс запуска автотестов в Test IT).

2. Суть — взаимодействие с системой

Суть — это то, что происходит, когда пользователь взаимодействует с UI. Это процесс, механика, стоящая за функцией. С точки зрения разработчика это поведение системы, а для пользователей это скорее процедура, которую надо пройти, чтобы достичь цели. Без этого пользователь не поймет, как работает система. В терминах подхода topic-based суть отражается в структурированном описании процессов (task topic), концепций (concept topic) или справочных материалах (reference topic).

Где найти

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

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

Как применять

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

• Изучите внутреннюю документацию. Возможно, она уже содержит прямые ответы на ваши вопросы.

• Задавайте разработчикам вопрос: «Что делает эта функция (ее часть)?». Например: «При выборе даты в “Фильтр по дате” система обновляет таблицу, показывая данные за указанный период».

• Разбивайте сложные процессы на шаги.

3. Причина — назначение или ценность

Причина — это то, зачем нужна функция, какую проблему она решает. Без этого пользователь порой не понимает, почему она может быть полезна. В документации, согласно подходу topic-based authoring, причина указывается в описательной части статьи (topic description), содержащей назначение или ценность фичи или продукта.

Где найти

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

Как применять

• Задавайте вопрос: «Какую проблему решает эта фича? Для кого она?». Например: «Фильтр по дате нужен, чтобы быстро найти данные для отчета».

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

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

  Пример из инструкции Test IT по созданию тестов с помощью ИИ-модели:

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

В качестве примера возьмем простую функцию — поиск в приложении. Используя метод Mononoke, структура будет такой:

• Форма: Элементы интерфейса для описания — кнопка Фильтр в правой верхней части окна, вызывающая окно с полями для ввода и кнопками Применить, Сохранить и Закрыть.

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

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

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

Чек-лист

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

Преимущества

• Четкость. Метод разбивает задачу на три понятные части, спасая от потенциального хаоса.

• Универсальность. Подходит для любой фичи — от кнопки до сложной аналитической системы.

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

• Эффективность. Чек-лист «Форма, суть, причина» помогает не упустить важное и экономит время.

Как внедрить

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

• Создайте шаблон. Для каждой фичи продумайте три раздела: форма (UI), суть (процесс), причина (ценность).

• Задавайте вопросы. При постановке задачи уточняйте: «Что это за элемент? Как он работает? Зачем нужен?». Общаться с людьми приходится немало, необходимо заранее формулировать вопросы точно, чтобы понять суть и не тратить время команды.

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

• Обучайте команду. Если работаете с другими техписами, поделитесь формулой и обсудите, как ее лучше применить в этой или других задачах (например, при подготовке сценариев для обучающих видео).

Заключение

Метод из Mononoke — мой способ справиться с неопределённостью в работе технического писателя. Он помогает видеть UI (форма), понимать процессы (суть) и находить назначение (причина), делая документацию понятной и полезной. Попробуйте применить её в своём проекте — и, возможно, вы почувствуете себя героем, изгоняющим хаос из мира IT. А если вы не технический писатель и не собираетесь им становиться — уверен, методу Mononoke найдётся применение и в вашей сфере.

Спасибо за внимание!