Между разработчиком и официальной документацией всегда ощущается неловкое расстояние
"Не понимаю документацию, значит моя компетенция низка?" Я долго так верил.
1. "Похоже, я единственный, кто не понимает"
Фреймворки, библиотеки, REST‑API, облачные сервисы… Большинство из них теперь хорошо задокументированы. Проблема в том, что… я не понимаю, как это работает.
В начале я так думал.
"А… я просто недостаточно опытен. Если продолжу учиться, то когда-нибудь смогу легко читать эту документацию…"
И я усердно читал. Но:
- Принцип работы мне не ясен
- Не могу отличить теоретический материал от практических примеров
- Читал, но при написании кода руки не двигаются
- Почему же документация так обширна…
Сейчас я считаю себя разработчиком, который не слышит слово «новичок». Но даже сейчас, когда открываю новую библиотеку, в голове звучит:
"Вау… опять начинается…"
Я понимаю, что недостаток навыков – не единственная причина.
2. Документация обычно написана с точки зрения автора
Главная причина, по которой документация тяжела, – это то, что большинство официальных материалов написаны с точки зрения «мозговой схемы автора».
- Автор уже
- знает внутреннюю структуру
- понимает, почему был выбран такой дизайн
- осведомлен о ограничениях
- знает, где и как вызывается функция
- Поэтому в документации обычно описываются:
- какие параметры принимает метод
- какой тип возвращается
- какие исключения могут возникнуть
- что можно сделать с этим
Проблема в том, что мы не являемся создателями программы.
Нас интересуют такие вопросы:
- "С чего начать?"
- "Как решить текущую проблему? Где в документации это описано?"
- "В каких ситуациях нужен этот параметр?"
- "Когда вызывается эта строка кода?"
Но документация отвечает так:
"Этот параметр используется для выполнения foo с помощью стратегии bar для baz."
…и хочется сразу запустить пример.
3. "Моя документация тоже будет непонятной для других"
Смешно, но я тоже пишу документацию для своих API и библиотек. Тогда я тоже пишу с точки зрения автора.
- "Эта функция делает…"
- "Этот эндпоинт принимает…"
- "Возвращает JSON в таком формате…"
- "При успехе/неудаче ответ выглядит так…"
И думаю:
"Разве это не достаточно дружелюбная документация?"
Но реакция коллег обычно такова:
- "Можешь объяснить устно?"
- "Есть документация, но я бы просто спросил, это быстрее."
Самое смешное – иногда я не могу понять собственную документацию.
Открываю старый API и вижу:
"Эй… это я написал? Почему объяснение такое странное…?"
Тогда я понял:
- Писать документацию не значит, что она сразу будет понятной.
- Я не имею права ругать официальную документацию за непонятность. 😅
4. Официальная документация изначально «не читается» – это нормально
У каждого проекта есть хотя бы одна библиотека или пакет, который вы постоянно открываете.
Интересно, что:
- При первом чтении вы думаете: "Что это вообще значит…?"
- В конце проекта вы перечитываете и понимаете: "А, теперь ясно…"
Часто я думаю:
"Неужели я действительно прочитал это раньше, но тогда не понял?"
Почему так происходит?
- Чтобы понять документацию, нужен опыт и контекст.
- Чтобы набрать опыт, нужно первоначально попробовать сделать что‑то.
То есть, чтобы понять документацию, нужна уже понимание документации – странный цикл.
Я теперь считаю:
"Официальная документация не предназначена для однократного прочтения. Только после нескольких проектов она становится понятной."
Поэтому первое непонимание – это нормально.
5. Нелокализованные разработчики сталкиваются с дополнительной сложностью
У нас есть ещё «неанглоязычный» барьер.
- Мы читаем английские предложения.
- Технические термины нам уже знакомы.
- Мы любим книги и статьи, поэтому не чувствуем нехватки «чтения».
Но при чтении официальной документации мозг всё равно устаёт.
Это не из‑за недостатка навыков:
- Английский язык требует постоянных когнитивных затрат.
- И к этому добавляются
- новые концепции
- незнакомый дизайн API
- абстрактные примеры кода
То есть мы тратим больше энергии, чем другие, и, следовательно, устаём быстрее.
Когда я думаю: "Почему мне так тяжело читать официальную документацию?", я говорю себе:
"Я уже преодолеваю этот барьер и продолжаю двигаться вперёд."
6. Но у нас есть несколько «выживательных» навыков
Ниже перечислю несколько техник, которые я освоил.
6‑1. Отказаться от желания читать «с начала до конца»
- Официальная документация – это скорее «справочник + словарь».
- Это не учебник, где чтение с первой страницы до последней приводит к пониманию.
Поэтому я:
- Быстро просматриваю «Getting Started / Quickstart / Tutorial»
- Остальное считаю
- поиск
- помощь при возникновении проблем
6‑2. Сначала понять через пример, потом читать объяснение
- Пишу одну строку кода
- Получаю ошибку
- Ищу сообщение об ошибке, читаю документацию
Тогда текст меняется:
- При первом чтении: "Я не понимаю, что это значит…"
- После нескольких попыток: "А, это то, о чём я столкнулся…"
После неудачи документация становится «историей».
6‑3. Записывать заметки на своём языке
Официальная документация всегда на их языке. Поэтому я часто делаю заметки:
- "Если параметр true, это фактически режим
XXX" - "Эта функция – как фабрика, создающая X"
- "Запомни этот фрагмент, глубже понять позже…"
Когда я позже смотрю свои заметки, они становятся «своей» документацией, которая дополняет официальную.
7. Это не твоя вина
Если ты дошёл до конца этой статьи, значит, ты тоже когда‑то задумывался о том, почему официальная документация кажется непонятной.
- Слова, которые не дают понять
- Секции, которые нужно искать снова
- Понимание, которое приходит только после решения проблемы
Помни:
- Ты не одинок.
- Многие опытные разработчики тоже сталкиваются с тем же.
- Даже те, кто ежедневно использует библиотеку, чаще ищут ответы в Stack Overflow или GitHub Issues, чем в официальной документации.
Официальная документация изначально сложна, и это не твоя ошибка.
Мы просто:
- Если не понимаем – перечитываем
- Если всё равно не понимаем – пишем код
- Если не получается – снова читаем
- И в итоге, однажды, понимаем, почему автор написал так.
Это часть того, что значит быть разработчиком.
Поэтому, если ты сейчас разочарован, скажи себе:
"Ты не ошибаешься. Ты просто проходишь через нормальный процесс разработки."
Мы все продолжаем писать код, открываем десятки вкладок и продолжаем двигаться вперёд. 🙂
Комментариев нет.