Документация, которую вы видите впервые

Ситуация: вам дали ссылку на документацию продукта, о котором вы знаете только название. Через час нужно сказать, подходит ли он, а через день — начать на нём писать.

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

Первое: у документации есть жанры, и они отвечают на разные вопросы

Самый полезный способ смотреть на любую документацию дал Daniele Procida в системе Diátaxis: тексты делятся на четыре жанра по двум осям — служат ли они изучению или работе, и передают ли они действия или знание.

Практическая ценность картинки — в диагностике собственных ошибок. Три самые частые:

• Искать «почему» в reference. Справочник по параметрам не объясняет модель. Вы решите, что документация плохая, а вам просто нужен раздел Explanation или Design.
• Учиться по how-to. Рецепт решает задачу, не строя картины. Пять рецептов подряд не складываются в понимание — они складываются в набор заклинаний.
• Работать по tutorial. Обучающий проход намеренно упрощён: там нет обработки ошибок, нет настроек безопасности и нет продакшн-соображений. Код из туториала в проде — источник отдельного класса инцидентов.

Не всякая документация организована по Diátaxis явно, но жанры в ней всё равно есть, и первое действие — опознать, какие разделы к какому жанру относятся. Это занимает две минуты и определяет, куда идти дальше.

Протокол первых двадцати минут

Порядок действий, который стоит выполнять механически, не думая. Он одинаково работает для облачного сервиса, библиотеки и внутреннего сервиса вашей компании.

Комментарии к шагам, где есть неочевидное.

Шаг 1, URL. Структура адреса часто говорит больше, чем страница: /en/latest/, /v2.3/, /docs/current/, /api/2024-06-01/. Слово latest — тревожный сигнал: оно может означать «последний релиз», а может — «текущее состояние главной ветки, ещё не вышедшее». Если есть переключатель версий, поставьте свою немедленно, до чтения. Читать документацию не той версии — самый дешёвый способ потерять день.

Шаг 2, оглавление. Не читать, а именно просмотреть заголовки целиком — все, включая те, которые кажутся ненужными. Цель одна: знать, что в этой документации есть. Дальше вы будете искать не в поисковике, а в конкретном разделе, и это в разы быстрее.

Шаг 4, changelog. Даже если вы только знакомитесь. Список последних изменений за две минуты даёт понимание, живой ли проект, что авторы считают ошибками прошлого дизайна и куда всё движется.

Шаг 5, ограничения. Самый недочитанный раздел и самый ценный. Именно здесь написано, что вас укусит: лимиты запросов, максимальные размеры, поведение при превышении, известные несовместимости.

Шаг 7, исходники документации. Ссылка «Edit this page» или «Improve this doc» ведёт в репозиторий. Оттуда вы получаете три вещи: историю изменений страницы (когда её последний раз трогали), возможность локального поиска по всей документации сразу и понимание, насколько документация связана с кодом.

Шаг 8, проверка поиска. Введите в поиск слово, которое точно есть в тексте (например, из заголовка, который вы только что видели). Если поиск его не находит — он сломан или ищет только по заголовкам, и дальше надо пользоваться site: во внешнем движке.

Как искать внутри документации

Встроенный поиск на сайтах документации в среднем плохой: он ищет по заголовкам, не понимает синтаксиса и не умеет в точные фразы. Четыре обходных пути, по возрастанию мощности.

1. Внешний движок с site:.

site:docs.example.com "rate limit" 429
site:docs.example.com inurl:reference timeout

2. Карта сайта. Файл sitemap.xml в корне — это полный список страниц. Скачать и просмотреть его быстрее, чем кликать по разделам:

curl -s https://docs.example.com/sitemap.xml | rg -o 'https://[^<]+' | sort | head -50

3. Локальная копия. Если документация лежит в репозитории (а она почти всегда лежит), клонируйте и ищите локально:

git clone --depth 1 --filter=blob:none https://github.com/OWNER/REPO
rg -n -i "idempot" REPO/docs/
rg -n -i "default" REPO/docs/reference/ | rg -i "changed|deprecat"

Локальный поиск даёт то, чего не даёт веб-интерфейс: регулярные выражения, контекст вокруг найденного, поиск сразу по всем версиям (если они в ветках) и возможность посмотреть историю конкретного абзаца.

4. Объединённые индексы. DevDocs держит документацию десятков языков и библиотек в одном поиске и работает офлайн. Локальные аналоги — Zeal и Dash. Когда вопрос «как называется этот метод», объединённый индекс быстрее любого веба.

Слова-маркеры: как вытащить из документации границы

Самое ценное в документации — не описание счастливого пути, а места, где сказано, чего система не обещает. Эти места редко вынесены в отдельный раздел, но они опознаются по устойчивым формулировкам. Поиск по маркерам — приём, который стоит трёх часов чтения.

Практика: открыв незнакомую документацию по важной для вас подсистеме, прогоните по ней пять-шесть маркеров из таблицы. За десять минут вы получите список всего, что в этой системе не гарантировано, — то есть карту будущих инцидентов. По-русски эти же маркеры искать бесполезно: нормативные формулировки живут в английском оригинале, и это одна из причин искать в оригинале, а не в переводе (глава 10).

Отдельно про at least once, at most once и exactly once: эти три формулировки определяют, что вам придётся написать в своём коде, и они почти всегда спрятаны в одном абзаце посреди раздела про доставку. Найти их — первая задача при работе с любой очередью.

Где спрятано самое полезное

Два раздела заслуживают отдельного упоминания, потому что их наличие само по себе — сигнал о зрелости продукта.

Справочник ошибок. Список кодов ошибок с условиями возникновения — редкость и большая ценность. Если он есть, прочитайте его целиком: это самый плотный по информации документ после changelog, и он экономит часы отладки. Как устроены сообщения об ошибках и что в них какая часть значит — глава про сообщения об ошибках.

Политика устаревания. Документ, в котором написано, сколько версий поддерживается и как объявляют о поломках. Он отвечает на вопрос «насколько безопасно строить на этом надолго» лучше, чем любые обещания на главной странице.

Признаки документации, которой можно верить

Оценивать корпус документов стоит осознанно и быстро — до того, как вы построите на нём решение.

Отдельный сильный признак, который стоит проверять первым: есть ли в документации хоть одно место, где авторы говорят «так делать не надо». Документация, состоящая только из возможностей, писалась для витрины. Документация, в которой есть предостережения, антипаттерны и разделы вида «когда не стоит использовать», писалась для тех, кто будет это эксплуатировать.

Тревожные признаки: примеры, которые не запускаются; отсутствие любых упоминаний версий; раздел «Getting started», за которым сразу идёт API reference и больше ничего; страницы, помеченные «TODO» годами; идеально гладкий текст без единого упоминания ограничений — это, скорее всего, маркетинг, а не документация.

Схема как документация: OpenAPI, JSON Schema, protobuf

Отдельный и очень плотный источник — машиночитаемое описание интерфейса. Если у сервиса есть спецификация OpenAPI, .proto-файлы или JSON Schema, они точнее прозы по трём причинам: их проверяет сборка, по ним генерируются клиенты и они не отстают от кода.

# скачать спецификацию и посмотреть, какие вообще есть операции
curl -s https://api.example.com/openapi.json > api.json
jq -r '.paths | keys[]' api.json | head -40

# какие поля обязательны в конкретной модели
jq '.components.schemas.Order.required' api.json

# где в схеме есть перечисления — это готовый список допустимых значений
jq -r '.. | objects | select(has("enum")) | .enum | @csv' api.json | sort -u | head

# для protobuf: полное описание сервиса прямо с работающего сервера
grpcurl -plaintext localhost:9090 describe

Что из схемы читается сразу и не читается из прозы: обязательность полей, форматы, допустимые значения перечислений, коды ответов, пагинация, версия API. Что из схемы не читается: смысл полей, взаимные ограничения («либо одно, либо другое»), побочные эффекты и порядок вызовов. За этим — в прозу и в примеры. Как устроена хорошая справочная документация API — глава в треке технического письма.

Как за час решить, подходит ли продукт

Частая задача: не «найти ответ», а «оценить кандидата». Документация — основной материал для этого, и читать её надо в определённом порядке, потому что маркетинговая часть всегда сверху, а существенная — снизу.

1. Ограничения и квоты (10 минут). Начните с конца. Максимальные размеры, лимиты запросов, поведение при превышении. Если ваши объёмы близки к границе — дальше можно не читать.
2. Модель отказов (10 минут). Что происходит при недоступности зависимости, при разрыве соединения, при перезапуске. Если про это не написано ничего — это сам по себе ответ.
3. Модель данных и гарантии (15 минут). Порядок, дубликаты, атомарность, согласованность. Ищите по маркерам из таблицы выше.
4. Changelog за год (10 минут). Частота релизов, число ломающих изменений, как о них предупреждают.
5. Матрица совместимости и сроки поддержки (5 минут). До какого момента ваша версия платформы будет поддерживаться.
6. Один исполняемый пример (10 минут). Запустите quickstart целиком. Если он не работает — это информация о качестве всего остального.

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

Когда документация расходится с кодом

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

1. Проверьте версию документации. В половине случаев расхождения нет, а есть чтение не той версии.
2. Найдите утверждение в исходниках. Поиск по коду (глава 3) отвечает точно.
3. Посмотрите тесты. Тест — исполняемая формулировка намерения. Если поведение покрыто тестом, оно намеренное; если нет — возможно, это случайность реализации, на которую нельзя опираться.
4. Проверьте экспериментом на своей версии. Пять минут, и вопрос закрыт для вашего случая.
5. Заведите issue. Если документация действительно неверна — это дешёвый вклад, который экономит время следующим, и заодно проверяет вашу правоту руками мейнтейнеров.

Отдельно про автогенерируемую документацию (Javadoc, godoc, docs.rs, OpenAPI-схемы). У неё специфический профиль: сигнатуры и типы всегда точны, потому что берутся из кода; смысл, ограничения и взаимосвязи отсутствуют, потому что их никто не писал. Практический вывод: автодоки отвечают на «что принимает и что возвращает» и не отвечают на «когда это вызывать и что будет, если не так». За вторым идите в тесты и в обсуждения.

Внутренняя документация: тот же протокол, другие поправки

Всё сказанное применимо к документации вашей компании, с тремя поправками:

• Датировка важнее вдвое. Внутренние документы редко имеют политику устаревания; страница трёхлетней давности выглядит так же, как вчерашняя. Первое, что надо найти, — дату и автора.
• Автор доступен. Это главное преимущество внутренней документации: можно спросить. Пять минут разговора часто заменяют час археологии — про то, как спрашивать, глава 10.
• Источник истины часто не там, где кажется. Реальные знания могут жить в ADR, в описаниях инцидентов, в комментариях к пулл-реквестам и в дашбордах, а не в вики. Про жанры внутренних документов — трек Техническое письмо.

Разбор: двадцать минут в документации незнакомой очереди

Задача: понять, можно ли построить на этом сервисе обработку платежей. Требование: не терять сообщения и не обрабатывать одно дважды.

Минуты 0–2. URL и версия. Адрес вида /docs/latest/ — переключателя версий нет. Первый вывод: датировка утверждений будет проблемой, придётся сверяться с changelog. Ищем номер текущей версии — он в разделе релизов.

Минуты 2–5. Оглавление целиком. Замечены разделы: Concepts, Producing, Consuming, Delivery guarantees, Operations, Limits. Уже отсюда видно, что нужный нам ответ, скорее всего, в Delivery guarantees, а неприятные сюрпризы — в Limits.

Минуты 5–8. Маркеры. Прогоняем по всей документации at least once, exactly once, not guaranteed, best effort, order. Находим абзац: порядок гарантируется в пределах одного раздела и только при отключённых параллельных повторах. Это условная гарантия — ровно тот случай, который теряется во всех пересказах.

Минуты 8–12. Limits. Максимальный размер сообщения, максимальное время удержания, поведение при превышении: сообщения отбрасываются молча, но пишется метрика. Отдельно: лимит на число одновременных получателей. Записываем — это и есть будущие инциденты.

Минуты 12–15. Changelog за год. Обнаруживается строка: «default visibility timeout changed from 30s to 60s». Значит, все статьи и ответы старше этого релиза дают неверное умолчание, и наши расчёты повторной доставки надо строить от текущего значения.

Минуты 15–18. Ошибки и отказы. Есть справочник кодов ошибок и раздел про поведение при недоступности. Хороший признак: авторы думали не только про счастливый путь.

Минуты 18–20. Проверка встроенного поиска и вывод. Поиск по слову «idempot» не находит ничего, хотя в тексте оно встречалось, — поиск слабый, дальше пользуемся site:. Итог: гарантия «не менее одного раза», порядок условный, дубли возможны, значит, идемпотентность обработчика — наша обязанность, и это надо закладывать в проект.

Двадцать минут дали три вещи, которых нет ни в одном обзоре: точную формулировку гарантии с условием, список лимитов и знание об изменившемся умолчании.

Ещё один быстрый тест зрелости: посмотрите, как документация обращается с ошибками своих же примеров. Наличие раздела «частые проблемы при запуске примера» означает, что авторы видели, как этим пользуются реальные люди, а не только писали текст.

Типичные ошибки

1. Читать документацию не той версии. Первое действие — поставить свою версию, а не листать.
2. Идти в reference за пониманием. Справочник отвечает на «что», а не на «почему».
3. Не смотреть оглавление целиком. Пятнадцать минут на карту экономят часы поисков.
4. Верить встроенному поиску. Проверьте его заведомо известным словом; часто быстрее site: или локальный rg.
5. Пропускать раздел ограничений. Это карта будущих инцидентов.
6. Считать отсутствие упоминания разрешением. Не описано — значит, не гарантировано, а не «можно».
7. Копировать код из туториала в продакшн. Туториал намеренно упрощён и не содержит обработки ошибок.
8. Спорить о поведении вместо чтения исходников. Расхождение документации и кода решается за минуту поиском по коду.

Мини-практика

Возьмите продукт, которым пользуетесь каждый день, и за пятнадцать минут ответьте по его документации на четыре вопроса. Почти наверняка вы обнаружите, что не знали хотя бы двух ответов.

1. Какой максимальный размер чего-нибудь у него есть и что происходит при превышении? Ищите в разделе ограничений.
2. Какое поведение он явно не гарантирует? Ищите по маркерам not guaranteed, undefined, best effort.
3. Что помечено устаревшим прямо сейчас? Ищите deprecated и загляните в политику устаревания.
4. Какое умолчание менялось за последний год? Ищите в changelog слово default.

Ценность упражнения в том, что все четыре ответа — это будущие инциденты, о которых вы узнаете либо сейчас за пятнадцать минут, либо потом за несколько часов ночью.

Мини-итог

• Документация состоит из четырёх жанров; они отвечают на разные вопросы, и половина неудач — это поход не в тот жанр.
• Протокол двадцати минут: версия в URL, оглавление целиком, reference, changelog, ограничения, глоссарий, исходники доков, проверка поиска.
• Встроенный поиск обычно слабее, чем site: во внешнем движке или локальный rg по клону документации.
• Самая ценная часть документации — формулировки границ. Их находят поиском по маркерам: undefined, not guaranteed, best effort, deprecated, default, at most.
• Признаки доверия: версия, исполняемые примеры, описанные умолчания, поведение при отказах, changelog, дата изменения, ссылки в код, раздел known limitations.
• Расхождение документации и кода — норма; порядок разрешения: версия, исходники, тесты, эксперимент, issue.
• Автогенерируемая документация точна в сигнатурах и пуста в смыслах.

Источники

• Diátaxis — систематика технической документации (Daniele Procida): diataxis.fr.
• Google, Technical Writing Courses — публичный курс по устройству технических документов: developers.google.com/tech-writing.
• Write the Docs — сообщество и руководства по документации: writethedocs.org.
• PostgreSQL Documentation, «Transaction Isolation» — пример раздела, где явно описано расхождение реализации со стандартом: postgresql.org/docs/current/transaction-iso.html.
• DevDocs — объединённый офлайн-индекс документации: devdocs.io.

Что дальше

Бывает и так, что документации нет вовсе или она не отвечает. Тогда источником становится сам проект — его код и его история. Когда документации нет: исходники, история, трекер.