Модуль 9: Техническая документация
Цель: Научиться быстро читать и понимать техническую документацию на английском: API docs, README, Stack Overflow, RFC, спецификации.
Словарь: +200 слов | Уровень: B2
Типы документации
Основные типы
- API documentationдокументация API
- READMEфайл с описанием проекта
- changelogжурнал изменений
- specificationспецификация
- RFC (Request for Comments)запрос комментариев (стандарт)
- tutorialруководство
- guideгайд
- referenceсправочник
Общие термины документации
Структура
- overviewобзор
- getting startedначало работы
- installationустановка
- configurationнастройка
- usageиспользование
- examplesпримеры
- troubleshootingустранение неполадок
- FAQчасто задаваемые вопросы
Действия
- deprecatedустаревший
- obsoleteустаревший (полностью)
- legacyустаревший (но поддерживаемый)
- breaking changeкритическое изменение
- backward compatibleобратно совместимый
- experimentalэкспериментальный
- stableстабильный
- betaбета-версия
API документация
HTTP методы и статусы
- endpointконечная точка API
- requestзапрос
- responseответ
- payloadполезная нагрузка (данные)
- headerзаголовок
- query parameterпараметр запроса
- path parameterпараметр пути
- authenticationаутентификация
- authorizationавторизация
- rate limitлимит запросов
Типичная структура API docs
GET /api/users/{id}
Description: Retrieves a user by ID.
Parameters:
- id (path, required): The user's unique identifier
Headers:
- Authorization: Bearer {token}
Response:
- 200 OK: User object
- 404 Not Found: User not found
- 401 Unauthorized: Invalid token
Структура README
Типичные секции
- Title + Description — Название и описание проекта
- Badges — Значки (build status, version, license)
- Installation — Инструкции по установке
- Usage — Примеры использования
- API Reference — Справка по API
- Contributing — Как внести вклад
- License — Лицензия
Фразы в README
- Clone the repositoryКлонируйте репозиторий
- Install dependenciesУстановите зависимости
- Run the following commandВыполните следующую команду
- See the documentationСмотрите документацию
- Pull requests are welcomePR приветствуются
- Please read CONTRIBUTING.mdПрочитайте CONTRIBUTING.md
Stack Overflow
Термины
- questionвопрос
- answerответ
- accepted answerпринятый ответ
- upvoteголос за
- downvoteголос против
- duplicateдубликат
- closedзакрыт
- reputationрепутация
Полезные фразы для поиска
- [python] how to read file — поиск по тегу
- user:123456 — ответы конкретного пользователя
- is:answer — только ответы
- score:10 — с рейтингом 10+
Сообщения об ошибках
Типичные ошибки
- undefined is not a functionundefined не является функцией
- cannot read property X of undefinedне могу прочитать свойство X у undefined
- module not foundмодуль не найден
- permission deniedдоступ запрещён
- connection refusedсоединение отклонено
- timeout exceededпревышено время ожидания
- out of memoryнедостаточно памяти
- stack overflowпереполнение стека
Git и GitHub терминология
Основные термины
- repository (repo)репозиторий
- commitкоммит
- branchветка
- mergeслияние
- pull request (PR)запрос на слияние
- issueзадача/проблема
- forkфорк (копия репозитория)
- cloneклонировать
- pushотправить изменения
- pullполучить изменения
PR и Code Review
- LGTM (Looks Good To Me)Всё хорошо
- WIP (Work In Progress)В процессе
- RFC (Request For Comments)Запрос комментариев
- nitмелочь, незначительное замечание
- blockerблокирующая проблема
- approvedодобрено
- changes requestedтребуются изменения
Практика
Упражнение 1: Прочитайте README
Откройте README популярного проекта на GitHub (React, Vue, Express) и найдите:
- Как установить библиотеку
- Базовый пример использования
- Ссылку на документацию
Упражнение 2: API Docs
Откройте документацию любого API (GitHub API, OpenWeather API) и найдите:
- Как получить API ключ
- Эндпоинт для получения данных
- Примеры запросов и ответов
Упражнение 3: Stack Overflow
Найдите на Stack Overflow решение проблемы на английском. Переведите основные шаги решения.