---
title: "Введение"
description: "Зачем нужна модель документации на основе семи действий."
doc_version: "2025-01-09"
last_updated: "2026-08-09"
canonical_url: "https://7act.org/ru/rationale/"
language: "ru"
license: "CC BY 4.0"
---

# Введение

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

## Фреймворков, инструментов и форматов документации недостаточно

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

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

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

## От типов контента к потребностям пользователей

Выход из этой ситуации — перенести внимание с того, что следует написать, на то, какие потребности пользователей следует удовлетворить. Для этого нужно взять на себя ответственность за стратегическую сторону документации — то есть за контент-стратегию, — а не создавать материалы по заранее заданным структурным шаблонам. Такой подход полностью совместим с фреймворками документации вроде Diátaxis, DITA и другими: он задаёт направление и цель создателям документации, а те уже используют доступные им типы контента, элементы и инструменты.

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

![Сэндвич документации: фреймворки и типы контента сверху, потребности пользователей посередине, а форматы и цепочки инструментов снизу.](https://passo.uno/uploads/sandwich-2.jpg)

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

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

## Модель документации на основе семи действий

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

Как я уже говорил, ядро модели — *действия*. Я выделил семь действий, которые, на мой взгляд, охватывают значительную часть целей потребителя документации. Они отражают распространённые способы взаимодействия пользователей с документацией в разных продуктах и предметных областях: Оценить (Распознать), Понять (Изучить), Исследовать (Открыть), Практиковаться (Тренироваться), Вспомнить (Припомнить), Разрабатывать (Интегрировать) и Устранить неполадки (Решить).

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

## Заключение

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

Модель также может стать основой для [метрик документации и постановки целей](https://passo.uno/docs-observability-do11y/) (do11y). Вместо того чтобы смотреть только на просмотры страниц или оценки удовлетворённости, команды могут отслеживать, насколько хорошо документация поддерживает каждое действие. Например, конверсия из документации во внедрение продукта может измерять эффективность оценки, а время до решения проблемы — успешность устранения неполадок.

Как это часто бывает с теоретическими моделями, эта модель не подкреплена обширными исследованиями или факторным анализом. Она распространяется КАК ЕСТЬ, и ни при каких обстоятельствах вы не можете возложить на меня ответственность за испорченный обед. Тем не менее я надеюсь, что она даст техническим писателям полезную точку зрения для создания более осмысленной документации.

![Пиксельная сцена в библиотеке с Индианой Джонсом и семью действиями документации.](https://passo.uno/uploads/indy.jpg)

## Sitemap

- [Модель документации на основе семи действий](https://7act.org/ru/index.md)
- [Введение](https://7act.org/ru/rationale/index.md)
- [Действия](https://7act.org/ru/actions/index.md)
- [Оценить](https://7act.org/ru/actions/appraise/index.md)
- [Понять](https://7act.org/ru/actions/understand/index.md)
- [Исследовать](https://7act.org/ru/actions/explore/index.md)
- [Практиковаться](https://7act.org/ru/actions/practice/index.md)
- [Вспомнить](https://7act.org/ru/actions/remember/index.md)
- [Разрабатывать](https://7act.org/ru/actions/develop/index.md)
- [Устранить неполадки](https://7act.org/ru/actions/troubleshoot/index.md)
- [Глоссарий](https://7act.org/ru/glossary/index.md)
- [Skill модели документации на основе семи действий](https://7act.org/ru/skill/index.md)