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