Ну, сами посудите: это не мультфильм, а готовая методичка по типам пользователей доки. Каждый
🟣 Крош (кролик-СДВГ-шник). Он прочитает первый абзац и побежит делать. Ему нужен TL;DR, кнопка «сделай уже» и ноль предисловий про то, зачем это все придумано. Если дать ему простыню контекста, то он закроет вкладку с докой на второй строке.
🟣 Копатыч (превед медвед). Идет по инструкции строго по шагам, от первого до последнего, и звереет, если пропущен хоть один пункт или порядок действий скачет. Идеальный тестировщик пошаговых гайдов: если Копатыч застрял — застрянет любой.
🟣 Пин (пернатый с говором немецкого водопроводчика). Ему не нужна не история про «зачем», а точный референс: какие параметры, какие типы данных, что возвращает эндпоинт. Лирика про пользу продукта его только раздражает, поэтому его сразу нужно отправлять к API-справочнику.
🟣 Совунья (nuff said). Эксперт, которая читает документацию и морщится от слова «просто». Для нее «разжеванный» текст выглядит как неуважение к ее опыту — ей нужен хардкорный режим, а не повторение матчасти.
🟣 Нюша (которая свинья). Ей важно не «как это работает», а как это будет выглядеть и ощущаться в итоге: красивый пример, скриншот готового результата, картинка «до/после». Сухая техническая логика без визуала ее не зацепит.
Пять смешариков = пять разных типов читателей одной документации. Из этого, кстати, теоретически может произрастать и идея Diataxis: tutorial для Кроша, how-to для Копатыча, reference для Пина, explanation для Совуньи.
(Для свиньи, к сожалению, отдельный тип документации пока не завезли 🤷)
Так что перед следующим командным мозговым штурмом на тему «а надо ли это объяснять подробнее» просто задумайтесь: а для кого мы сейчас пишем, для Кроша или для Совуньи? Ответ обычно все расставляет по местам 😮