Фронтенд-розкладка: шаблон сторінки документації, що змушує користувачів гортати (а не покидати)

Шаблон: сторінка документації, що поводиться пристойно

Переможна розкладка документації нудна у кращому сенсі: передбачувана, швидка і не змушує читача переорієнтовуватися кожні 20 секунд. Ось шаблон, який послідовно тримає людей у прокручуванні.

Рекомендована структура (десктоп)

• Хедер: тонкий, стабільної висоти, без «банера оголошень», який штовхає всю сторінку вниз після завантаження.
• Ліва бічна панель: навігація на рівні продукту (розділи, версії) з гарною підтримкою клавіатури і зберіганням стану.
• Головна колонка контенту: 65–80 символів у рядку, щедрий міжрядковий інтервал, чітка ієрархія H2/H3.
• Права колонка (опційно): внутрішній змістовий TOC, який підсвічує поточний розділ і не смикається.
• Футер: не рекламний щит. Тримайте його стриманим.

Рекомендована структура (мобільна)

• Верхній хедер з одним значком меню.
• TOC перетворюється на згортальну панель «На цій сторінці».
• Бічна панель стає повноекранним вікном‑drawer із пошуком у верхній частині.

Це не дизайнерський тренд. Це зменшувач когнітивного навантаження. Більшість читання документації — це не «читання». Це добування: сканування, стрибок, перевірка, копіювання, повернення.

Жарт №1: Сторінка документації без стабільного TOC схожа на пейджер без батарейки — технічно все ще пейджер, але здебільшого спричиняє шкоду.

Чому цей шаблон працює (механіка)

Користувачі залишаються, коли відбуваються три речі:

1. Вони завжди знають, де знаходяться. Хлібні крихти, підсвічений пункт навігації та положення у TOC це дають.
2. Вони можуть передбачити, де буде інформація. Послідовні заголовки і стабільна розкладка будують ментальну карту.
3. Сторінка їм не заважає. Без зсувів верстки, без прилипаючих елементів, що перекривають заголовки, без ривків при скролі.

«Розкладка документації» звучить як фронтендова проблема, доки ви не побачите, як ваша служба підтримки перетворюється на людський кеш, бо користувачі не можуть знайти те, що вже написано.

Необхідні принципи розкладки

1) Стабільність важливіша за хитромудрість

Ваша навігація і TOC не повинні рухатися через пізно завантажені шрифти, ін’єковані банери або A/B‑експерименти. Якщо сторінка зсуватиметься під час читання, ви фактично вводите випадкові переривання. Люди не створять баг; вони підуть.

Проєктуйте для передбачуваної геометрії. Зарезервуйте місце для всього, що може з’явитися: бейджі версій, виділені блоки, кнопки «копіювати», перемикачі мови. Це не гламурно. Це працює.

2) Зробіть колонку контенту читабельною за замовчуванням

Читабельне ≠ «більший шрифт». Це означає:

• Довжина рядка близько 65–80 символів для прозового тексту.
• Міжрядковий інтервал близько 1.5–1.7.
• Помітне стилювання коду з достатньою контрастністю і правилами переносу рядків, що не руйнують команди.
• Заголовки, які виглядають як заголовки. Не вигадуйте хитрощі з типографікою.

3) Навігація — це залежність виробництва

Якщо ваша ліва бічна панель ламається, ви випустили інцидент. Це не «просто UI». Ставтеся до неї як до критичного сервісу: тестуйте, моніторьте та версіонуйте.

4) TOC — не декоративний елемент; це панель керування

Права колонка TOC має виконувати три завдання:

• Показати структуру сторінки одним поглядом.
• Дозволити користувачам переходити, не втрачаючи контексту.
• Показувати прогрес і місцезнаходження (підсвічування активного розділу).

Коли TOC правильно підсвічує, користувачі довіряють сторінці. Коли підсвічування неточне, користувачі перестають довіряти усім.

5) Пошук має бути швидким, обмеженим і прощаючим

Пошук у документації, що повертає маркетингові сторінки — це не пошук; це саботаж. Фільтруйте за продуктом/версією, підтримуйте нечіткі збіги для частих помилок, індексуйте заголовки і блоки коду розумно. Автодоповнення повинно відповідати швидко, інакше воно перетворюється на черговий дратівливий ящик.

6) Кожна взаємодія має берегти позицію скролу

Відкриття бічної панелі, копіювання коду, переключення вкладок у прикладах, розгортання виділень — жодна з цих дій не повинна смикати сторінку. Зберігайте позицію скролу, уникайте фокусних пасток і використовуйте якорі всередині сторінки правильно.

Інформаційна архітектура, що не заперечує користувачів

Розкладка — це фізична будівля; інформаційна архітектура — це вказівники. Обидві можуть бути неправильними такими способами, що важко сформулювати, але легко відчути.

Надавайте перевагу неглибоким шляхам зі зрозумілими групуваннями

Читачі документації не досліджують ваш продукт заради розваги. Вони намагаються виконати завдання з часовим бюджетом і легким відчуттям паніки. Тримайте глибину навігації розумною. Якщо ваша бічна панель вимагає 5 розгортань, щоб дістатися до «Rate limiting», користувач навчиться іншому вмінню: покидати сторінку.

Версії належать до розкладки, а не до контенту

Не захаращуйте сторінки фразами «Для v2 лише» у тексті. Розмістіть вибір версії в передбачуваному місці (хедер або бічна панель) і зробіть його липким. Переконайтеся, що при перемиканні версій:

• є спроба потрапити на ту саму сторінку в іншій версії,
• є плавний запасний варіант з чітким повідомленням,
• не ламаються URL, якими можна ділитися.

Нехай «На цій сторінці» відображає реальний контент

TOC має генеруватися з реальних заголовків (H2/H3) і не має включати декоративні заголовки або прихований контент. Якщо ви додаєте заголовки лише для стилю, ви забрудните TOC і зробите сторінку відчутно довшою, ніж вона є.

Цікаві факти та історичний контекст (бо ми не винайшли це вчора)

• Факт 1: Патерн «три колонки» для документації (навігація + контент + TOC) став поширеним, коли портали для розробників виросли в 2010‑х, і одиничні сторінки документації перетворилися на повноцінні сайти.
• Факт 2: Робота Якова Нільсена з юзабіліті вебу в 1990‑х сприяла патернам, дружнім до сканування — короткі абзаци, змістовні заголовки та очевидна навігація — задовго до того, як «DX» стало професією.
• Факт 3: «Вище згину» було важливіше на початку вебу, бо пропускна здатність і рендеринг були повільні; сьогодні стабільна розкладка і швидка взаємодія важливіші за запихування всього вгору.
• Факт 4: Поява sticky у CSS зробила постійні TOC значно простішими, ніж JavaScript‑хакі десятирічної давнини.
• Факт 5: Cumulative Layout Shift (CLS) увійшов у розмови інженерів, коли з’явилися Core Web Vitals, перетворивши «відчуття смикання» на вимірювану регресію.
• Факт 6: Пошук у документації покращився, коли статичні генератори сайту почали випускати структуровані дані та послідовну розмітку заголовків — індексація стала кращою, бо HTML став менш хаотичним.
• Факт 7: Кнопка «копіювати в буфер» для блоків коду стала звичною, коли браузери стандартизували Clipboard API; раніше багато сайтів використовували крихкий Flash або хитрі обхідні шляхи.
• Факт 8: Сучасне захоплення dark mode частково відповідь на те, що розробники весь день працюють у терміналах; це ергономіка і вподобання, а не лише естетика.

Продуктивність — це UX: бюджети, метрики та пастки

У продакшні ви не сперечаєтесь з графіками затримок. У UX документації теж не варто сперечатися з метриками продуктивності. Повільна сторінка документації — не просто дратівлива, вона перешкоджає засвоєнню. Робоча пам’ять читача — не черга з нескінченним запасом.

Виберіть метрики, що корелюють з «залишанням у прокручуванні»

Для сторінок документації мене цікавлять:

• LCP (Largest Contentful Paint): чи з’являється контент швидко?
• CLS: чи сторінка залишається на місці під час завантаження?
• INP (Interaction to Next Paint): чи сторінка реагує на взаємодії (відкрити навігацію, розгорнути розділи, пошук) без відчуття «залипання»?
• TTFB: чи змушує нас чекати origin/CDN?
• Довгі задачі у браузері: чи блокуємо ми основний потік скриптами?

Встановлюйте бюджети всерйоз

Сторінка документації повинна бути дешевшою за ваш маркетинговий сайт. Ви не можете називатися «орієнтованими на розробників», якщо відправляєте 900KB JavaScript для рендерингу сторінки, що на 95% складається зі статичного тексту.

Розумні початкові бюджети:

• < 200KB gzipped JavaScript для обгортки документації (бажано менше)
• < 100KB gzipped CSS
• Файли шрифтів: мінімальні варіанти, попереднє завантаження обдумано, з запасними метриками
• Зображення: зазвичай відсутні у верхній частині сторінки документації; якщо є — вони повинні мати width/height

Одна цитата, бо це досі правда

«Надія — не стратегія.» — Gene Kranz

Пастки продуктивності, специфічні для розкладок документації

• Пастка: скрізь прилипання (sticky). Надто багато прилипаючих елементів викликають перекриття, перерахунок і непрацездатні-якорі. Хедер + TOC + банер cookie — і ви отримуєте 40% в’юшпорту, відданого під chrome.
• Пастка: TOC будується шляхом парсингу на клієнті. Якщо ви парсите DOM після завантаження, щоб побудувати TOC, ризикуєте ривками і некоректними якорями. Генеруйте TOC на етапі збірки, коли це можливо.
• Пастка: «корисна» гідратація. Гідратувати всю сторінку заради кількох інтерактивних компонентів — це як запуск Kubernetes‑кластера для cron‑завдання. Працює, але це крик про допомогу.
• Пастка: веб-шрифти без запобіжників. Пізно завантажені шрифти спричиняють CLS, а блоки коду особливо чутливі: ширина символів змінюється і рядки переносяться по‑іншому.
• Пастка: індексація пошуку на клієнті при завантаженні сторінки. Побудова індексу в браузері може бути дорогою. Якщо треба — ліну‑завантажуйте і не блокуйте рендеринг.

Жарт №2: Я колись бачив сторінку документації, якій потрібно було 12MB JavaScript, щоб пояснити, як зберегти 12MB JavaScript.

Практичні завдання: команди, виводи, рішення

Хочете менше відмов? Вимірюйте. Хочете стабільну розкладку? Доведіть це. Нижче реальні завдання, які я дав би SRE‑орієнтованій фронтенд‑команді. Кожне має команду, приклад виводу, що це означає, і рішення, яке ви приймаєте.

Завдання 1: Перевірте TTFB від origin з хоста, схожого на продакшн

cr0x@server:~$ curl -s -o /dev/null -w "namelookup:%{time_namelookup} connect:%{time_connect} ttfb:%{time_starttransfer} total:%{time_total}\n" https://docs.example.com/guides/rate-limits
namelookup:0.007 connect:0.021 ttfb:0.312 total:0.419

Що це означає: Time to first byte ~312ms; total 419ms. Не жахливо, але для документації бажано стабільно нижче.

Рішення: Якщо TTFB стрибкоподібний або >500ms, пріоритизуйте кешування CDN, налаштування origin і виключення динамічного рендерингу для переважно статичного контенту.

Завдання 2: Підтвердіть заголовки кешування (чи ми взагалі використовуємо CDN?)

cr0x@server:~$ curl -sI https://docs.example.com/guides/rate-limits | egrep -i "cache-control|age|etag|last-modified|cf-cache-status|x-cache"
cache-control: public, max-age=0, must-revalidate
etag: "9b3e-1a2f3c"
age: 0
x-cache: MISS

Що це означає: Ви змушуєте перевірку і втрачаєте кеш. Age 0 свідчить, що об’єкт не залишається “гарячим”.

Рішення: Для незмінних артефактів збірки встановлюйте довге кешування (з хешованими іменами) і дозвольте HTML реалідуватися дешево. Не душіть CDN правилами «max-age=0» скрізь.

Завдання 3: Перевірте TLS і повторне використання з’єднань (прихований податок латентності)

cr0x@server:~$ curl -s -o /dev/null -w "remote_ip:%{remote_ip} ssl_verify:%{ssl_verify_result} http_version:%{http_version}\n" https://docs.example.com/
remote_ip:203.0.113.10 ssl_verify:0 http_version:2

Що це означає: HTTP/2 працює; TLS перевіряється нормально.

Рішення: Якщо ви застрягли на HTTP/1.1, платите за додаткові з’єднання на сторінках з великою кількістю ресурсів. Спочатку виправте конфігурацію edge; це зазвичай дешеві виграші.

Завдання 4: Виміряйте реальну вагу сторінки ключових маршрутів

cr0x@server:~$ curl -s https://docs.example.com/guides/rate-limits | wc -c
186442

Що це означає: HTML ≈186KB. Це багато для текстової сторінки; можливо, він містить вбудований JSON, важку розмітку навігації або надто багато стану на клієнті.

Рішення: Якщо HTML регулярно перевищує ~100KB для типових сторінок, проведіть аудит на дубльовану навігацію, непотрібні вбудовані дані та надмірну розмітку від генератора.

Завдання 5: Знайдіть незжаті ресурси (ширина каналу, яку ви не планували витрачати)

cr0x@server:~$ curl -sI https://docs.example.com/assets/app.js | egrep -i "content-encoding|content-length"
content-length: 842311

Що це означає: Заголовка gzip/brotli не показано. Може бути, що на edge файл не стиснутий або ваш запит не погодив компресію.

Рішення: Переконайтеся, що brotli/gzip увімкнені і що CDN віддає стиснуті варіанти. Якщо ви не бачите content-encoding, тестуйте з заголовком Accept-Encoding.

Завдання 6: Явно перевірте узгодження brotli/gzip

cr0x@server:~$ curl -sI -H "Accept-Encoding: br,gzip" https://docs.example.com/assets/app.js | egrep -i "content-encoding|vary|content-length"
vary: Accept-Encoding
content-encoding: br
content-length: 214903

Що це означає: Brotli працює; стиснений розмір ≈215KB, що ще великий, але не катастрофічний.

Рішення: Якщо стиснений JS перевищує ваш бюджет, зменшіть область гідратації, розділіть бандли і приберіть «оболонку документації» залежностей, що належать додатку, а не документації.

Завдання 7: Перевірте Core Web Vitals у вашому моніторинговому пайплайні (синтетика)

cr0x@server:~$ lighthouse https://docs.example.com/guides/rate-limits --quiet --chrome-flags="--headless" --only-categories=performance
Performance: 71
First Contentful Paint: 1.8 s
Largest Contentful Paint: 3.3 s
Cumulative Layout Shift: 0.19
Total Blocking Time: 420 ms

Що це означає: LCP доволі повільний, CLS занадто високий для сторінки для читання, а блокування основного потоку суттєве.

Рішення: Нападіть на CLS спочатку (це чисте тертя), потім зменшіть час виконання JS (TBT/INP). LCP часто покращується побічно.

Завдання 8: Виявіть джерела зсувів верстки через headless trace (швидкий сигнал)

cr0x@server:~$ lighthouse https://docs.example.com/guides/rate-limits --quiet --chrome-flags="--headless" --output=json --output-path=/tmp/lh.json

cr0x@server:~$ jq -r '.audits["cumulative-layout-shift"].details.items[]? | "\(.node.selector) \(.score)"' /tmp/lh.json | head
.header-announcement 0.07
code pre 0.05
.sidebar 0.03

Що це означає: Банер оголошень, блоки коду і бічна панель зсуваються.

Рішення: Зарезервуйте місце для хедера; встановіть метрики запасних шрифтів для коду; зафіксуйте ширину бічної панелі; визначте розміри зображень і вбудованих елементів.

Завдання 9: Перевірте блокуючі рендеринг CSS/JS (класичне «чому текст зʼявляється пізно?»)

cr0x@server:~$ curl -s https://docs.example.com/guides/rate-limits | grep -Eo '<script[^>]+>' | head -n 5