Читаем документацию, RFC и changelog
Тема дорожной карты · Английский для IT
🔊 Словарь терминов с произношением →
Чтение документации — навык, который отличает инженера, решающего проблему за пять минут, от того, кто час перебирает ответы на форумах. Английская техническая документация устроена предсказуемо: у неё стандартная структура разделов (Getting started, Guides, Reference, FAQ), стандартный язык требований (MUST, SHOULD, MAY из RFC 2119), стандартный формат истории изменений (changelog с разделами Added, Changed, Deprecated, Removed, Fixed, Security) и стандартный словарь обсуждений в issue-трекерах (reproduce, workaround, upstream, wontfix). Зная эти конвенции, можно не читать документацию целиком, а сразу открывать нужный раздел и вычитывать из него ответ техникой скимминга и сканирования. Раздел разбирает пять тем: структуру документации, язык RFC, changelog и release notes, словарь GitHub Issues и техники быстрого чтения.
Как произносится
Documentation /ˌdɒkjʊmɛnˈteɪʃən/, docs /dɒks/, reference /ˈrɛfərəns/ (ударение на первый слог, «рЕференс», не «рефЕренс»), guide /ɡaɪd/ («гайд», u не произносится), tutorial /tjuːˈtɔːriəl/ («тьютОриэл»), FAQ по буквам или /fæk/, RFC по буквам /ˌɑːr ɛf ˈsiː/, specification /ˌspɛsɪfɪˈkeɪʃən/, spec /spɛk/, changelog /ˈtʃeɪndʒlɒɡ/, release notes /rɪˈliːs noʊts/, deprecated /ˈdɛprəkeɪtɪd/, issue /ˈɪʃuː/, workaround /ˈwɜːrkəraʊnd/, upstream /ˈʌpstriːm/, skim /skɪm/, scan /skæn/, glossary /ˈɡlɒsəri/, appendix /əˈpɛndɪks/, prerequisites /priːˈrɛkwɪzɪts/ («прирЕквизитс»), troubleshooting /ˈtrʌblʃuːtɪŋ/, migration guide /maɪˈɡreɪʃən ɡaɪd/.
Как употребляется
Как о документации говорят в команде:
- It's in the docs, under Reference → Configuration. — Это в документации, раздел Reference, подраздел Configuration.
- Read the Getting started first, then the guide on auth. — Сначала Getting started, потом руководство по аутентификации.
- The spec says the header MUST be present. — Спецификация требует наличия заголовка.
- Check the changelog before upgrading; 3.0 has breaking changes. — Посмотри changelog перед обновлением, в 3.0 несовместимые изменения.
- Someone reported the same issue upstream; there's a workaround in the thread. — Кто-то уже сообщил об этом в основной проект, в треде есть обход.
- Skim the RFC for the MUSTs and skip the rest. — Пробеги RFC по требованиям MUST и пропусти остальное.
- The docs are outdated; the API changed in 2.4. — Документация устарела, API поменялся в 2.4.
- RTFM — грубоватое «читай документацию»; в вежливой форме have you checked the docs?
Ловушки
Первая ловушка — читать документацию линейно, как книгу: она справочник, и читают её по оглавлению и поиску. Вторая — переводная документация: русские переводы отстают на версии и содержат ошибки; при расхождении верен английский оригинал. Третья — reference с ударением на второй слог. Четвёртая — воспринимать SHOULD как «должен»: в RFC это «настоятельно рекомендуется», а «должен» — MUST. Пятая — игнорировать changelog при обновлении: раздел Breaking changes существует именно для того, чтобы его прочитали до обновления. Шестая — искать ответ в issue-трекере по русскому описанию проблемы: ищите английский текст ошибки. Седьмая — documentation как «документы»: документация проекта — docs, юридические документы — documents, «документы на подпись» — paperwork.