(спойлер: дело не в лени)
Есть один странный парадокс в IT. Все говорят: «Документация — это важно», и те же самые люди через 5 минут: гуглят ошибку и копируют ответ со Stack Overflow.
Почему так?
Не потому что разработчики ленивые. А потому что документация часто… ну, скажем мягко — не помогает.
Покажите код, а не философию
Типичная документация написана так: “Use the configuration provider to initialize the environment…”
Разработчик читает это и думает: «Окей… а где код?»
Ему не нужно «как правильно устроен мир». Ему нужно:
- вставить кусок кода
- чтобы он заработал
- желательно с первого раза
Если этого нет — он закрывает вкладку.
Документация почти всегда врёт
(иногда случайно)
Ты открываешь доку, делаешь всё «по инструкции»… и ничего не работает. Почему?
- API уже поменяли
- параметры другие
- пример устарел
После пары таких случаев в голове закрепляется: «Документации верить нельзя».
Быстрее загуглить, чем читать
Разработчик не выбирает «правильный путь». Он выбирает самый быстрый.
Читать документацию:
- найти нужный раздел
- разобраться
- адаптировать
Гуглить:
- вставить ошибку
- открыть первый результат
- скопировать
Угадай, что победит 🙂
Документация отвечает не на те вопросы
Разработчик приходит с конкретным: «Как подключить X к Y?»
А ему выдают:
- историю проекта
- архитектурные принципы
- 20 экранов текста
Где-то там, возможно, есть ответ, но искать его целый квест.
Документация говорит «что есть»
Разработчик думает «как сделать».
Документация: «Вот список функций».
Разработчик: «Как мне это использовать прямо сейчас?».
Есть негласное правило: читай код
В разработке давно есть простая мысль: «Код — это правда. Всё остальное — мнение».
Почему так:
- код не устаревает отдельно от себя
- код показывает реальные кейсы
- код не пытается быть красивым — он просто работает
Поэтому многие сразу идут в исходники, тесты, примеры и часто быстрее разбираются.
Документацию пишут «для галочки»
Иногда создаётся ощущение, что документацию пишут чтобы она просто была, для отчёта, «ну надо же».
А не для человека, который:
- впервые видит этот API
- сидит под дедлайном
- уже слегка злой
В итоге получается текст, который никто не хочет читать.
Плохие примеры — это отдельный вид боли
Ты открываешь пример… и он:
- не запускается
- использует старую версию
- слишком искусственный
И в голове возникает: «Если даже пример не работает — что тогда вообще работает?». После этого вкладка закрывается без сожаления.
Документацию читают только когда всё плохо
Никто не сидит вечером такой: «Почитаю-ка документацию, для души»
Её открывают, когда:
- что-то сломалось
- дедлайн близко
- уже немного паника
И если в этот момент она не помогает, то второго шанса у неё не будет.
Что вообще с этим делать
Хорошая новость: проблема решаемая.
Плохая: нужно менять подход.
Писать не «что это», а «как сделать»
Не: «Метод делает X»
А: «Как загрузить файл за 3 шага»
Давать код. Рабочий. Сразу
Без лишнего. Чтобы можно было:
- скопировать
- вставить
- запустить
И получить результат.
Держать документацию в актуальном состоянии
Если она устарела — это уже не документация. Это ловушка.
Строить по сценариям
Нужны простые вещи:
- «Начать за 5 минут»
- «Типичные ошибки»
- «Как сделать X»
Принять реальность
Разработчики всё равно будут гуглить, читать форумы, смотреть код и это нормально.
Задача документации — не конкурировать с этим. А быть быстрее и понятнее.
Итог
Разработчики не читают документацию не потому, что ленятся.
А потому что она часто:
- не помогает
- не совпадает с реальностью
- проигрывает гуглу по скорости
Хорошая документация — это не «описание системы».
Это штука, которая экономит время.
И как только она начинает это делать — её внезапно начинают читать 🙂
