Пишем README и документацию на английском
Тема дорожной карты · Английский для IT
🔊 Словарь терминов с произношением →
README — первое, что видит человек, открывший репозиторий, и документация — то, по чему проект будут судить через год после ухода автора. Англоязычная техническая документация имеет свой стиль, который отличается от русского академического: короткие предложения, повелительное наклонение (Run the command вместо The command should be run), второе лицо (you) вместо безличных конструкций, активный залог, настоящее время (The server returns 404, а не will return), конкретика вместо оценок (takes about 2 minutes вместо fast). Структура README: название и однострочное описание (A CLI for exporting user data to CSV); бэджи (badges: сборка, версия, лицензия); Features или Why — зачем; Installation / Getting started / Quickstart; Usage с примерами; Configuration — переменные и опции в таблице; Examples; Development / Contributing — как собрать и отправить PR; Testing; Troubleshooting / FAQ; Roadmap; License; Acknowledgements / Credits. Приёмы: заголовки как глаголы или существительные (Install, Configure, Configuration), но не смешивать; пример команды сразу за описанием; вывод команды показывать; таблицы для опций (Option | Type | Default | Description); Note / Warning для предупреждений; ссылки вместо копирования чужой документации; Prerequisites до Installation. Стилевые правила гайдов Google и Microsoft: sentence case в заголовках (только первая буква заглавная); Oxford comma; for example вместо e.g. в прозе; избегать please в инструкциях (Run the command, не Please run the command); избегать simply, just, easy, obviously — они унижают читателя, у которого не получилось; избегать we о читателе; избегать идиом и юмора, которые не переводятся; писать you can только когда это действительно опция. Слова: README /ˈriːdmiː/, badge — значок, snippet — фрагмент кода, placeholder — заполнитель (<your-token>), boilerplate — шаблонный код, walkthrough — пошаговый разбор, cheat sheet — шпаргалка, changelog, docstring — документация в коде, inline comment, API reference, autogenerated — сгенерированная автоматически, single source of truth, docs as code — документация в репозитории рядом с кодом, linter для прозы (Vale).
Как произносится
README /ˈriːdmiː/ («рид-ми»), badge /bædʒ/, snippet /ˈsnɪpɪt/, placeholder /ˈpleɪshoʊldər/, boilerplate /ˈbɔɪlərpleɪt/, walkthrough /ˈwɔːkθruː/ (l немая, с «θ»), cheat sheet /ˈtʃiːt ʃiːt/, docstring /ˈdɒkstrɪŋ/, imperative /ɪmˈpɛrətɪv/, passive voice /ˈpæsɪv vɔɪs/, active voice /ˈæktɪv vɔɪs/, second person /ˈsɛkənd ˈpɜːrsən/, sentence case /ˈsɛntəns keɪs/, title case /ˈtaɪtl keɪs/, Oxford comma /ˈɒksfərd ˈkɒmə/, prerequisites /priːˈrɛkwɪzɪts/, installation /ˌɪnstəˈleɪʃən/, usage /ˈjuːsɪdʒ/ («Юсидж», с глухим «с»), configuration /kənˌfɪɡjəˈreɪʃən/, contributing /kənˈtrɪbjuːtɪŋ/, acknowledgements /əkˈnɒlɪdʒmənts/, license /ˈlaɪsəns/, autogenerated /ˌɔːtoʊˈdʒɛnəreɪtɪd/.
Как употребляется
Фрагмент README в правильном стиле:
## Installation
Requires Node 22 or later.
bash* *npm install -g user-export* *
## Usage
Export a user's orders to CSV:
bash* *user-export --user 42 --out ./orders.csv* *
The command prints the number of rows written. Set DB_URL before running; see Configuration.
> Note: exports over 100k rows stream to disk and can take several minutes.
Переписывание в правильный стиль: The configuration file should be edited by the user in order to specify the database URL → Set DB_URL in the config file. It is possible to run tests using the following command → Run tests with make test. Simply click the button and it will work → Click Export. The download starts within a few seconds.
Ловушки
Первая ловушка — пассив и безличность из русской традиции (it is recommended that, should be configured): пишите configure, we recommend. Вторая — please в каждой инструкции: в документации это лишнее. Третья — simply, just, easy: читатель, у которого не получилось, чувствует себя глупо. Четвёртая — будущее время (the server will return): документация описывает поведение в настоящем. Пятая — заголовки в Title Case вперемешку с sentence case: выберите одно (Google и Microsoft рекомендуют sentence case). Шестая — русские кальки actual version, in the nearest future: current version, soon. Седьмая — usage с звонким «з». Восьмая — README без Prerequisites: половина issue «не работает» отсюда. Девятая — документация в Word или Confluence отдельно от кода: она устаревает через месяц; docs as code в репозитории обновляется вместе с PR.