​​Воронка технической сложности документа.
Прочитал статью про превью ссылок в Telegram. Статья хорошо выстроена по сложности и подаче материала.

Сначала смысл фичи объясняют как для ребёнка, буквально говорят, на какую кнопку нажать. А затем, от заголовка к заголовку, техническая сложность статьи повышается, так что до следующего заголовка дочитает всё меньше читателей. Это можно назвать воронкой технической сложности документа. (Только что придумал термин. Если это уже как-то названо — скажите, я поправлю.)

В целеполагании технического документа есть основные вопросы: кто читатель, какова цель читателя, какова цель бизнеса. Я уже разбирал их на примере комикса про Kubernetes. Давайте посмотрим на каждую главу этой статьи и ответим на эти вопросы. Заметьте, как от заголовка к заголовку сужается аудитория, меняется цель читателя, но строго выдерживается цель бизнеса.

Instant Views Explained
Для новичков. Задача читателя — наверное, удовлетворить любопытство. Задача бизнеса — чтобы читатели пользовались instant view, читали статьи прямо в мессенджере и не уходили в браузер.

How does this work?
Для тех, кто понимает основы интернета: ссылки, домены, шаблоны веб-сайтов. Задача читателя — понять, почему у одних сайтов есть instant view, а у других нет, и как сделать это для своего сайта. Задача бизнеса — замотивировать читателей делать шаблоны, чтобы instant view работал и пользователи не выходили из приложения.

Join buttons
Для владельцев сайта и телеграм-канала одновременно. Читатель здесь узнаёт, что в instant view можно добавить ссылку для подписки на канал в один клик. Задача бизнеса — ещё больше замотивировать читателей. Вот меня замотивировали. Конверсия? Конечно, хочу. Займусь сайтом — точно сделаю себе шаблон и ссылку для подписки на @docops.

Instant View Editor
Для тех, кто хочет и может сделать шаблон для сайта. Задача читателя — понять, насколько это сложно, какие есть инструменты. Задача бизнеса — облегчить вход в разработку шаблонов.

Templates tutorial
Для тех, кто прочитал прошлую главу и решился делать. Задачи читателя — написать первый шаблон. Задача бизнеса — получить ещё один шаблон.

И наконец, в конце статьи — переход к документации разработчика. Там сразу начнётся хардкорный справочник по формату данных в шаблонах. Дойдут в основном те, кто осилил tutorial. А остальным и незачем это видеть.

You're now ready to move on! Знаете другие примеры хорошей документации? Или вам больно от очень плохой документации? Присылайте примеры @nick_volynkin или в чат @docsascode.