← К списку разделов
#### §4.05 Ролевое описание **Время:** 60 мин чтение + 40 мин = 100 мин **Что узнаешь:** почему описание системы «для всех» — это описание ни для кого, и как ролевое описание делает документацию реально используемой **В одном предложении:** ролевое описание — это описание системы с позиции конкретной роли, фиксирующее ровно то, что нужно этой роли для работы; именно такое описание, а не «полное», становится рабочим инструментом. --- **Сигнатура понятий:** - **Ролевое описание** — это описание системы, построенное с точки зрения конкретной роли: содержит то, что нужно знать и делать носителю роли, и опускает то, что для этой роли нерелевантно --- **Мем, который снимается.** «Хорошая документация должна быть полной, описывать систему со всех сторон.» На самом деле «полное описание» не существует (§4.02: любое описание неполно), а документация «для всех» не используется никем: она слишком большая, чтобы найти нужное, и слишком общая, чтобы ответить на конкретный вопрос. Разработчик, открывая документацию продукта, ищет технические детали реализации. Пользователь ищет, как решить свою задачу. Менеджер ищет бизнес-логику. Для каждой роли нужно своё описание - ролевое. --- **Определение из источника.** В системном подходе (FPF A.2) ролевое описание определено как описание системы, построенное с позиции конкретной роли в деятельности. Ролевое описание содержит: что роль должна знать о системе, чтобы выполнять свою функцию; какие аспекты системы для этой роли критичны; какие действия с системой роль выполняет. Ролевое описание - не «упрощение» полного описания, а принципиально другая форма. Описание архитектуры для архитектора содержит компоненты и связи. Описание той же системы для оператора - процедуры работы и сигналы тревоги. Это не разные уровни детализации одного описания, а описания с разных ролевых позиций, каждое полное внутри своей позиции. --- **Развитие мысли.** Ролевое описание решает практическую проблему: как сделать так, чтобы описание системы реально использовалось теми, кто с ней работает. Проблема «документации ради документации» часто коренится в отсутствии ролевой позиции. Когда пишут «общее описание системы», его трудно читать, потому что непонятно, кому это читать и зачем. Когда пишут «описание для роли X», появляется конкретный читатель с конкретными потребностями, и можно проверить, отвечает ли описание на вопросы именно этого читателя. Ролевые описания одной системы не противоречат друг другу, а дополняют. Каждое отвечает на вопросы своей роли и ссылается на другие ролевые описания там, где нужны детали из другой позиции. Хорошая документационная система — это набор ролевых описаний с явными перекрёстными ссылками. Для созидателя ролевое описание - инструмент коммуникации. Когда нужно объяснить систему коллеге, ключевой вопрос - «в какой роли этот человек будет работать с системой?». Ответ определяет, что войдёт в объяснение. Системный мыслитель не рассказывает «всё о системе», он рассказывает «то, что нужно для этой роли». --- **Метод - минимальный шаг.** Практика «Ролевой фильтр» (40 мин): 1. Выберите систему и конкретную роль, для которой нужно описание (5 мин). 2. Запишите три вопроса, на которые эта роль должна получить ответ из описания системы: «Что мне нужно знать, чтобы...?» (10 мин). 3. Возьмите существующую документацию об этой системе и проверьте: отвечает ли она на три вопроса роли? Что нужно убрать (нерелевантное), что добавить (отсутствующее)? (15 мин). 4. Набросайте ролевое описание: только то, что нужно этой роли, в форме, которая отвечает на её три вопроса (10 мин). --- **Пример из жизни.** Сергей - методолог образовательной программы. Для одного и того же инструмента (системы управления обучением) ему нужно было объяснить работу трём группам: студентам, преподавателям и администраторам. Первую попытку, «полное описание», не читал никто. Тогда Сергей написал три ролевых описания. Для студентов: как подать домашнее задание, как посмотреть оценку, как задать вопрос преподавателю. Для преподавателей: как создать задание, как проверить работу, как поставить оценку. Для администраторов: как добавить нового пользователя, как настроить курс, как экспортировать отчёт. Каждое описание занимало одну страницу и отвечало ровно на нужные вопросы. Вопросов к Сергею стало в три раза меньше. --- **Типичная ошибка.** «Нам нужно одно общее описание, а не несколько.» Желание сэкономить на количестве документов понятно, но экономия оборачивается тем, что «общее» описание не используется и всё равно приходится объяснять каждой роли отдельно, только устно, каждый раз заново. Ролевые описания дороже при создании, но дешевле при эксплуатации. Вторая ошибка: описывать систему без явного указания, для какой роли это описание. Когда нет ролевой позиции, читатель не знает, насколько это описание относится к нему. Ролевая позиция — это не заголовок «Для продакт-менеджеров», а структура: описание построено так, что отвечает на вопросы именно этой роли. --- **Степени мастерства:** | Степень | Что происходит | Критерий перехода | |---------|----------------|-------------------| | 1. Объясняю | Могу объяснить, что ролевое описание строится с позиции конкретной роли и отвечает на её вопросы | Один раз выполнил практику «Ролевой фильтр» | | 2. Умею | Могу для любой системы создать ролевое описание для конкретной роли | Есть запись: система + роль + три вопроса роли + ролевое описание | | 3. Навык | При объяснении системы автоматически спрашиваю: «Для какой роли?» и строю объяснение под эту роль | Регулярность: каждое объяснение системы начинается с ролевой позиции | | 4. Мастерство | Помогаю командам перейти от «общей документации» к системе ролевых описаний | Есть кейс, где ролевые описания заменили нечитаемую «общую документацию» | --- **Проверка себя.** - Понимание: вы можете объяснить, почему описание системы для инженера и для пользователя — это не версии одного описания, а принципиально разные ролевые описания. - Поведение: когда вас просят «объяснить систему», вы сначала уточняете: «Для какой роли? Что вам нужно уметь делать с этой системой?» - Застревание: если ваше описание системы читают все, но никто не использует, вероятно, оно не ролевое. Попробуйте написать описание для конкретного человека с конкретной задачей. --- **Что дальше.** Ролевое описание описывает, как роли взаимодействуют с системой. Но прежде чем проектировать детали системы, нужно зафиксировать общую картину: как система будет применяться в контексте, кто, когда и зачем с ней работает. Следующий подраздел - о концепции использования: почему этот документ должен предшествовать детальному проектированию.
← Предыдущий раздел
Следующий раздел →