Структура доков: Getting started, Reference, Guides, FAQ
Тема дорожной карты · Английский для IT
🔊 Словарь терминов с произношением →
Хорошая техническая документация делится на четыре типа материалов, и модель Diátaxis, которую используют Django, Kubernetes, Cloudflare и многие другие, называет их так: Tutorials — пошаговые уроки для новичка, ведущие к результату (Build your first app); How-to guides — рецепты для конкретной задачи (How to configure TLS); Reference — сухое полное описание API, опций, команд (Configuration reference); Explanation — концепции и обоснования (How the scheduler works, Architecture overview). Названия разделов на сайтах документации: Getting started / Quickstart / Installation — с чего начать; Guides / How-to / Tutorials; Reference / API Reference / CLI Reference; Concepts / Overview / Architecture; Configuration; Examples / Recipes / Cookbook; FAQ; Troubleshooting / Common issues; Migration guide / Upgrading; Changelog / Release notes / What's new; Glossary; Contributing; Community / Support; Security / Security policy; Deprecation policy; Roadmap. Внутри страницы: Prerequisites — что нужно заранее, Overview, Usage — использование, Options / Parameters / Arguments, Returns — что возвращает, Raises / Throws — какие исключения, Examples, See also — связанные страницы, Notes, Caveats / Gotchas / Limitations — подводные камни, Known issues, Since / Added in — с какой версии, Deprecated since, Experimental / Beta / Stable — статус, Default — значение по умолчанию, Required / Optional, Type, Env var — переменная окружения. Метки в тексте: Note, Tip, Warning, Caution, Danger, Important — предупреждения разной силы. Ссылки: TL;DR — краткое резюме, Further reading, Read on, Next steps.
Как произносится
Tutorial /tjuːˈtɔːriəl/, how-to /ˈhaʊ tuː/, reference /ˈrɛfərəns/, explanation /ˌɛksplənˈeɪʃən/, quickstart /ˈkwɪkstɑːrt/, installation /ˌɪnstəˈleɪʃən/, overview /ˈoʊvərvjuː/, concepts /ˈkɒnsɛpts/, cookbook /ˈkʊkbʊk/, recipe /ˈrɛsəpi/ («рЕсипи», три слога), troubleshooting /ˈtrʌblʃuːtɪŋ/, glossary /ˈɡlɒsəri/, prerequisites /priːˈrɛkwɪzɪts/, caveat /ˈkæviæt/ («кЭвиэт»), gotcha /ˈɡɒtʃə/, limitation /ˌlɪmɪˈteɪʃən/, experimental /ɪkˌspɛrɪˈmɛntl/, default /dɪˈfɔːlt/, optional /ˈɒpʃənəl/, caution /ˈkɔːʃən/ («кОшен»), deprecation /ˌdɛprəˈkeɪʃən/, contributing /kənˈtrɪbjuːtɪŋ/.
Как употребляется
- Start with the quickstart, it takes ten minutes. — Начни с quickstart, это десять минут.
- The how-to on TLS assumes you've done the install guide. — Рецепт по TLS предполагает, что установка пройдена.
- Look it up in the reference; the guide doesn't list every option. — Посмотри в reference, в руководстве не все опции.
- The concepts page explains why, the reference explains what. — Страница концепций объясняет «почему», справочник — «что».
- Check Caveats before you rely on that flag. — Прочитай подводные камни, прежде чем полагаться на флаг.
- It's marked experimental; the API may change. — Помечено как экспериментальное, API может меняться.
- See the migration guide for 3.x. — Смотри руководство по миграции на 3.x.
- That's answered in the FAQ. — Это есть в FAQ.
Практическое правило поиска: «как сделать X» → How-to; «что делает опция Y» → Reference; «почему так устроено» → Concepts; «не работает» → Troubleshooting, затем Issues.
Ловушки
Первая ловушка — искать конкретную опцию в руководствах: полный список всегда в Reference. Вторая — пропускать Prerequisites: половина «не работает» из-за пропущенного шага подготовки. Третья — recipe с двумя слогами «ресип»: три слога /ˈrɛsəpi/. Четвёртая — caveat читать как «кавеат»: /ˈkæviæt/. Пятая — reference с ударением на второй слог. Шестая — не различать Note и Warning: у предупреждений есть иерархия, и Danger означает потерю данных. Седьмая — считать Getting started достаточным для продакшна: это учебный путь, а для эксплуатации нужны Concepts и Reference. Восьмая — documentation переводить как «документы»: docs и documents разные вещи.