Есть фраза, которую каждый программист однажды чувствовал, но не всегда формулировал:
“Мне не нужна документация, мне нужен пример.”
Именно об этом пишет Рахим Давлеткалиев в своей статье Examples Are the Best Documentation.
Он утверждает: примеры кода — самая эффективная форма документации, особенно в эпоху, когда разработчики работают сразу с десятками фреймворков и языков.
🧠 Почему формальная документация не работает
Официальные справочники вроде Python Docs или API Reference по сути создаются для экспертов — тех, кто уже "внутри экосистемы".
Но реальность такова:
- 💼 большинство разработчиков работают в нескольких контекстах — сегодня они пишут на TypeScript, завтра на Python, послезавтра на Go;
- 🧩 между переключениями нужно заново восстанавливать ментальную модель языка, синтаксиса и идиом;
- 📚 и именно в этот момент формальная документация оказывается бесполезной — она требует «разогрева мозга», а не помогает быстро приступить к делу.
Рахим приводит прекрасный пример: описание функции max в Python.
Вот как оно выглядит в документации:
max(iterable, /, *, key=None)
Return the largest item in an iterable or the largest of two or more arguments.
Чтобы понять это, нужно знать:
- что значит * и / в сигнатуре,
- что такое "keyword-only arguments",
- что вообще такое "iterable",
- и зачем параметр key.
А ведь на практике программист хотел просто узнать, как сравнить строки по длине!
✨ Идеальный пример вместо десяти абзацев
Автор показывает, что пять строчек кода способны заменить целую страницу документации:
max(4, 6) # → 6
max([1, 2, 3]) # → 3
max(['x', 'y', 'abc'], key=len) # → 'abc'
max([]) # ValueError: max() arg is an empty sequence
max([], default=5) # → 5
📘 Вот и всё. Без лишних терминов, без когнитивного шума — сразу понятно, как работает функция.
🧩 Примеры как форма коллективного интеллекта
Рахим упоминает проект clojuredocs.org, где пользователи сообщества Clojure сами добавляют примеры для стандартных функций.
Каждая страница там — это не сухая справка, а мини-учебник из реальных кейсов:
- 🪄 into показывает, как создавать коллекции разных типов;
- 🧱 spit — как записывать файлы;
- 🔄 map — как комбинировать функции.
Главное — рядом всегда есть связанные функции и контекст, а не изолированное описание.
То есть это не просто документация, а живая экосистема опыта, собранная сообществом.
🧰 Почему это особенно важно сегодня
Современная разработка строится на принципе быстрой интеграции и переиспользования.
Мы не изобретаем алгоритмы с нуля — мы комбинируем чужие решения, API, библиотеки и SDK.
И именно поэтому примеры:
- ⚙️ помогают быстрее начать работать, не вникая в теорию;
- 🧩 служат шаблоном для адаптации под свой проект;
- 🧠 работают как «оперативная память» при смене технологий.
Автор справедливо замечает:
«Я открываю документацию не ради учебника. Я просто хочу пример.»
И если документация — это "карта местности", то примеры — это GPS, который сразу ведёт к цели.
💬 Моё мнение: документация — это UX для мозга
Я полностью согласен с мыслью Рахима. В XXI веке документация — это не текст, а интерфейс.
Её задача — не демонстрировать знание, а минимизировать трение между человеком и кодом.
Лучшие проекты это уже поняли:
- 🦙 Hugging Face превращает каждую модель в страницу с рабочими сниппетами;
- ⚛️ React и Vue дают пример «Hello World» сразу в первом абзаце;
- 🐍 Python в Jupyter-ноутбуках стал самообучающимся инструментом.
Когда документация написана как UX-дизайн, а не как энциклопедия, — разработчик остаётся в потоке.
А значит, продукт побеждает.
🔗 Источники:
🧠 Пример — это не просто иллюстрация. Это сжатая инструкция по выживанию в экосистеме кода.