Спасаем разработчиков от лабиринта документации

Как я спасал API документацию от размытых ссылок

Проект trend-analisis рос, и с ним росла беда: разработчикам нужно было регистрироваться, читать документацию, переходить на API endpoint’ы — и каждый раз они путались в лабиринте вкладок и закладок. Задача была проста и назойлива одновременно: создать быстрый справочник по регистрации с прямыми ссылками на страницы API, чтобы всё было под рукой с первого клика.

Звучит просто? Нет, потому что простых задач не бывает, есть только те, что казались простыми в начале 😄

В поиске правильной структуры

Первым делом я разобрался, как люди вообще читают документацию. Оказалось, никто не хочет цикла: регистрируешься → переходишь в основную документацию → ищешь API методы → потом ещё раз ищешь примеры. Это как ходить пешком туда-обратно на протяжении всего проекта.

Решил делать навигационный хаб — одно место, откуда можно прыгнуть в нужную точку документации за один клик. Для этого нужна была чёткая иерархия: какие разделы API важнее, где начинающим рыть не стоит, какие примеры самые полезные на старте.

Архитектура справочника

Я подумал о структуре как о карте города: есть главные улицы (основные API методы), есть боковые (advanced features), есть где-то офис регистрации. Сделал справочник с тремя слоями:

1. Блок регистрации — с инструкциями и ссылкой на форму
2. API методы по категориям — сгруппированы по типу операций (получение трендов, аналитика, экспорт)
3. Примеры кода — непосредственно в справочнике, чтобы не прыгать по вкладкам

Познавательный момент про документацию

Знаете, почему DevTools в браузере показывает сетевые запросы? Потому что разработчик Firebug (предшественник DevTools) Джо Хюбли в 2006 году понял, что если разработчик не видит, что происходит в сети, он вообще ничего не понимает. Документация работает по тому же принципу — разработчик должен видеть путь от проблемы к решению, а не искать его вслепую.

Финальное решение

В итоге сделал: - Динамическое содержание — справочник парсит структуру API из docstrings и автоматически создаёт якоря - Sticky навигация — панель с ссылками висит слева, прокручиваются только примеры - QR-коды для мобильных — потому что люди читают документацию на телефоне, даже если не хотят в этом признаваться

Разработчики теперь открывают регистрацию, видят справочник, кликают на нужный endpoint — и вот они уже в нужной части документации. Без танцев с бубнами, без пяти вкладок браузера.

Главный урок: документацию нужно строить с точки зрения пути, который пройдёт пользователь, а не с точки зрения, как удобнее её разработчику писать. Когда ты думаешь о маршруте, а не о каталоге — всё встаёт на место.

Почему разработчик любит регулярные выражения? Потому что без них жизнь слишком скучна 😄