Английский для чтения документации

В документации любого инструмента рано или поздно встречается фраза примерно такого вида: This option is deprecated and will be removed in a future release; use the new setting instead, unless your configuration relies on the old behavior. Каждое слово в ней знакомо читателю с хорошей школьной базой, кроме разве что deprecated. Ошибаются обычно на последнем отрезке: unless читают как «и», и человек уходит с убеждением, что старую настройку надо заменить, хотя в оговорке сказано обратное. Слов хватило, а вот привычки к тому, как такие фразы устроены, нет.

Привычка эта тренируется отдельно от остального английского, и для неё не нужно говорить вообще.

Узнавание и речь — разные способности

Читать и говорить называют одним словом «знать язык», но это разные способности, и растут они почти независимо. Чтение — узнавание: слово и конструкцию надо опознать, воспроизводить их не требуется. Речь требует обратного: достать слово из памяти, собрать фразу, произнести. Поэтому встречаются люди, которые двадцать лет читают технические тексты свободно и не могут заказать кофе, и встречаются те, кто говорит бегло и путает на странице may с must.

Если разговорный у вас на нуле, а читать нужно уже сейчас, чтение не стоит откладывать до момента, когда «подтянется всё остальное». Для документации хватает узкого слоя языка, и его можно взять отдельно. Если же вам нужна именно речь, например на созвонах, смотрите статью про английский для переговоров; общий разбор того, что взрослые подтягивают и в каком порядке, собран в статье что подтягивают взрослые чаще всего.

У взрослого здесь есть преимущество перед школьником, которого он обычно не замечает. Он знает предметную область и поэтому предсказывает, что будет написано дальше: если страница описывает настройку тайм-аута, слово timeout он узнает почти без чтения. Школьнику такой опоры не хватает. Зато взрослый слабее в другом: заучивать слова списком, без контекста, ему труднее и скучнее, и это лишний довод брать слова с собственных страниц, а не из готового списка.

Как устроена фраза в документации

Документация пишется короче и плотнее обычной прозы, и у неё свой набор оборотов, которых в учебнике почти нет. Хороших новостей две: оборотов немного, и они повторяются в тексте любого продукта.

Первое — условия. If, when, unless, otherwise, provided that, as long as: за каждым из этих слов стоит развилка, и неверно прочитанная развилка означает неверное действие. The function returns null if the key does not exist, unless a default value is provided. Читается так: функция возвращает пустое значение, когда ключа нет, но правило отменяется, если задано значение по умолчанию. Привычка читать такое предложение справа налево, от исключения к правилу, сэкономит вам больше времени, чем любой словарь.

Второе — цепочки существительных. User session timeout configuration value: пять слов подряд без единого предлога, и главное слово здесь последнее, value, а все остальные его уточняют, справа налево. Русскому читателю это непривычно, потому что в русском главное слово стоит первым. Разбирать такую цепочку нужно с конца: значение настройки времени ожидания сессии пользователя.

Третье — отрицание, которое действует не на то слово, которое вы ожидаете. Not all requests are retried: повторяются не все, и это ещё не значит, что не повторяется ни один. The setting does not necessarily improve performance — настройка не обязательно ускоряет работу, и это не то же самое, что «замедляет». Эти ловушки надо знать заранее: в обычном разговоре человек переспросит, а страница не ответит.

Четвёртое — страдательный залог и безличные формулировки: is deprecated, is not supported, can be configured. Автор прячет себя, и действующее лицо приходится достраивать самому. Обычно это вы, система или конкретный компонент, и из контекста понятно, кто именно.

Пятое — блоки с предупреждениями. Note, Warning, Caution, Important выделяются на странице рамкой или цветом, и в них обычно лежит то, ради чего стоило открыть страницу: условие, при котором описанное выше не работает. Многие, наоборот, читают эти блоки в последнюю очередь, если читают вовсе. Сам я открываю страницу с них: два-три предложения в рамке сообщают больше, чем абзац вокруг.

Must, should, may: слова, за которыми стоит решение

В технических спецификациях модальные глаголы читаются жёстче, чем в разговорной речи. Принятое в таких документах соглашение, описанное в RFC 2119, различает несколько степеней. Must и must not означают абсолютное требование и абсолютный запрет. Should и should not означают, что есть веские основания поступить иначе, но, нарушая правило, вы должны понимать последствия. May означает, что действие необязательно: можно сделать, можно и не делать. Часто эти слова набирают прописными буквами, и это сигнал, что автор использует их в строгом смысле.

Проверка, которую я предлагаю на каждом занятии с таким читателем: подчеркните в странице все модальные глаголы и для каждого запишите по-русски, что обязательно, что рекомендовано и что необязательно. Чаще всего ошибаются в одном и том же месте: should читают как «должен», хотя в документации это «рекомендуется», а различие определяет, придётся ли вам переписывать вечером интеграцию или нет.

Отдельная пара — can и may. В обычном английском они взаимозаменимы. В документации can чаще означает «возможно технически», а may — «разрешено». Пробел между ними невелик, но для чтения прав доступа и условий использования он существенный.

Слова, которые узнаются неправильно

Часть словаря документации состоит из слов, которые русскому читателю кажутся знакомыми и означают другое. Несколько самых коварных:

• eventually — в итоге, в конце концов, а не «возможно»; если в тексте сказано, что данные eventually consistent, они сойдутся, но не сразу
• actual — фактический, настоящий, а не «актуальный»; для «актуального» в документации используется current или up to date
• resolve — не только «решить», но и определить: resolve a hostname означает найти по имени адрес
• support — поддерживать, в смысле «уметь работать с чем-то»: if a format is not supported, программа его не откроет, и никакой поддержки пользователя здесь нет
• default — по умолчанию, то есть то, что включено, пока вы ничего не меняли
• argument — аргумент вызова, параметр, а не спор

Список можно продолжать, но заводить его стоит самому, из тех слов, на которых вы споткнулись сами, потому что вашу область я угадать не могу.

Браузерный переводчик: где помогает и где нет

Переводчик, встроенный в браузер, сейчас переводит документацию намного лучше, чем несколько лет назад, и пренебрегать им глупо. Он хорош для первого прохода: понять, о чём страница, и решить, нужна ли она. Он плох в трёх местах. Он сглаживает модальные глаголы, нередко превращая must в «следует» и should в «должен». Он теряет область действия отрицания. И он переводит термины, которые лучше оставить: русскоязычные коллеги и русскоязычные форумы говорят «пул-реквест», а не «запрос на вытягивание», и если вы запомнили перевод, то поиск по форуму вам не поможет.

Я бы разделил так: переводчик годится для ответа на вопрос «о чём это», а на вопрос «можно ли удалять» отвечайте по английскому оригиналу. На тех страницах, где цена ошибки высока (миграции, права, удаление), оригинал читается всегда. Остальное можно пробежать глазами в переводе, если оно не касается ничего необратимого.

Версия страницы

Документация устаревает вместе с продуктом, и первое, что надо сделать при чтении, прежде чем разбирать хоть одно предложение, — найти номер версии. Он стоит в шапке страницы или в адресе, и у большинства проектов поиск показывает вперемешку страницы про давно прошедшие версии и про текущую. Полезно сравнить дату последнего обновления страницы с датой выхода версии: расхождение в несколько лет часто означает, что страницу давно не проверяли. Читателю, который выучил конструкцию и верно прочёл фразу, но открыл страницу не той версии, это не помогает. Если же вам нужно понять, что изменилось при обновлении, ищите разделы release notes, changelog, breaking changes и migration guide: именно там сосредоточены фразы с must и deprecated.

Как строить занятия, если нет общего экрана

Показать репетитору страницу целиком не получится: демонстрации экрана в видеокомнате нет. Для документации это почти не мешает, потому что разбирать всё равно приходится абзац за абзацем. Скопируйте тот, на котором споткнулись, в сообщение чата. В одно сообщение входит до четырёх тысяч знаков, а это два-три абзаца, на остальное достаточно дать ссылку. Писать в чат можно после того, как репетитор получил ваш контакт.

Дальше работа строится на вашем собственном материале. Разбирается абзац из вашей реальной работы: вы пересказываете его по-русски своими словами, без дословного перевода, и репетитор по ходу ловит те места, где пересказ разошёлся с оригиналом. Специалист сначала смотрит, где вы ошиблись, и объясняет уже после. Между занятиями вы делаете то же самое один-два раза в неделю, отмечая карандашом только конструкции, а не слова.

Чтение — половина дела, если вам предстоит работать в англоязычной команде. Вторая половина видна, например, на техническом интервью, где решение приходится проговаривать вслух: о ней подготовка к техническому интервью по алгоритмам. Школьное чтение, которое проверяют на экзамене (структура описана в статье структура ЕГЭ по английскому языку), строится на общих текстах и тренирует другое умение: следить за общей мыслью. Отчасти поэтому хороший школьный английский не защищает от ошибки с unless.

Начать поиск:

• репетиторы по английскому языку
• репетиторы для взрослых
• репетиторы по английскому языку с пробным занятием
• занятия по вечерам

С чего начинать, если вы только возвращаетесь к учёбе после перерыва, написано в статье репетитор для взрослого.

Вопросы и ответы

Достаточно ли читать, если разговаривать не нужно? Достаточно, пока работа ограничена текстами. Появятся созвоны — придётся добавлять слух, а переписка в чате потребует письма: это разные навыки, и у каждого свои занятия.

Сколько слов нужно знать для чтения документации? Универсального числа нет, и называть его я не стану: словарь сильно зависит от области, а числа из рекламных обещаний курсов к вашему продукту не относятся. Надёжнее ориентироваться на собственную тетрадь, куда вы записываете слова, которые встретились дважды. Когда за страницу вы подчёркиваете одно-два слова вместо десяти, объём достаточен. Слова из такой тетради запоминаются не сразу, и первые недели кажется, что вы стоите на месте. Перемена заметна позже: однажды вы читаете страницу и не подчёркиваете ни одного слова.

Не проще ли просто всегда пользоваться переводчиком? Проще, и многие так работают. Платить за это приходится на страницах, где оттенки модальных глаголов и область отрицания определяют результат: там сглаженный перевод даёт правдоподобный и неверный смысл, и вы узнаёте об этом по итогам, а не в момент чтения. Поэтому оригинал стоит читать хотя бы там, где ошибка стоит дороже полученного времени.