Как улучшить английский в документации

Я (@makushevkm) работаю техническим писателем в компании Documentat. Иногда я дорабатываю уже существующие документы или спецификации к API на английском. Как правило, такие документы написаны русскоязычными разработчиками, которые неплохо владеют английским. И всё же они часто допускают характерные грамматические, пунктуационные и стилистические ошибки.

Корень этих ошибок один — разные языковые механизмы. Нам бывает легко запутаться в употреблении временных форм, порядке слов или непонятно зачем придуманных артиклях. 

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

Правильно используйте артикли

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

Зачем эти артикли нужны?

Чтобы понимать, что вообще происходит.

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

Артикль объявляет, что стоящее за ним слово — это существительное или группа существительного (существительное с предшествующими определениями), но совершенно точно не глагол. Например, слово program может означать как действие — программировать, так и объект — программа. Но артикль добавляет однозначность: a program — программа.

Жёсткий порядок слов заслуживает отдельного курса лекций, здесь я ограничусь одним аспектом. В английском есть очень полезная фича: существительное служит определением к другому существительному, если стоит перед ним: the text message — текстовое сообщение, но the message text — текст сообщения. Обратите внимание на положение артикля — он предшествует всей конструкции, объявляя о её начале.

Посмотрите, как порядок слов и положение артикля меняют смысл простого словосочетания:

Как понять где нужно a/an, а где the? 

Формальный кодерский подход такой:

• Если ваша «переменная» (сущность, о которой идёт речь) стоит в единственном числе, является частью массива аналогичных «переменных» и упоминается впервые (необъявлена), «объявите» её при помощи неопределённого артикля a/an.

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

Обратите внимание, что в последнем примере артикль относится ко всему словосочетанию, где главное слово — method, а акроним FIFO выступает в роли определения. Если же акроним выступает в роли обычного существительного, то артикль не ставится: FIFO is a method to manage requests. Но на каждое правило есть исключение, и если вы откроете ту статью на Википедии, то найдёте их целый вагон. Всё из-за того, что авторы поленились каждый раз писать method и, когда они пишут the FIFO, они на самом деле имеют ввиду the FIFO method. Да, носители языка они такие.

Иногда выбор артикля существенно влияет на смысл всего предложения:

Когда a, а когда an?

Если следующий за артиклем звук согласный — a, если гласный — an. Буква значения не имеет:

Как видите, ничего сложного, но с произношением придётся разобраться. Если сомневаетесь в правильном звучании слова, проверяйте его по словарям (Cambridge, Merriam-Webster). 

Когда артикль не нужен?

Выше мы выяснили, что артикль не нужен перед акронимами (произносятся как слово), если только они не выступают в роли определения. То же самое справедливо для аббревиатур (произносятся по буквам), которые означают метод, протокол, состояние или вещество.

Также артикль не ставится, если:

• «необъявленных» сущностей много;

• сущность неисчисляемая;

• определена принадлежность сущности.

Правильно используйте определяющие существительные

Я уже упомянул эту замечательную придумку англичан: просто ставим существительные одно за другим, и первое служит определением второму. Они это называют «существительное в роли прилагательного», а я для простоты буду называть «определяющее существительное».

Очень удобная фича, всем рекомендую. Но неправильное её использование, равно как и неиспользование, превратит ваш текст в трудночитаемую мешанину. Чтобы разобраться, как же этим пользоваться, рассмотрим три распространённые ошибки.

Ошибка 1: Неиспользование определяющих существительных

Есть два способа сделать одно существительное определением к другому:

• Использовать определяющее существительное — The field contains the message text.

• Связать существительные предлогом — The field contains the text of the message.

Эти способы не всегда взаимозаменяемы, например, the text message означает «текстовое сообщение», однако the message of the text можно перевести как «главная мысль текста». Но в первом примере оба способа вполне легитимны — словосочетания читаются легко и однозначно.

Допустим, теперь мы имеем дело с «текстом сообщения об ошибке». Сравните:

• The field contains the error message text.

• The field contains the text of the message about the error.

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

Ошибка 2: Злоупотребление определяющими существительными

Допустим, теперь ошибка стала системной, а вместо текста сообщения в поле возвращается его текстовый идентификатор. Мы выучили предыдущий урок и пишем: The field contains the system error message text identifier.

Опять же, грамматически здесь всё нормально. Стилистически — плохо. Пока читатель доберётся до главного существительного, он уже забудет, что там было в начале, в итоге ему придётся перечитывать всё предложение с конца.

Но что же делать? Ведь второй способ явно будет ещё хуже. Элементарно — комбинируйте два способа: The field contains the text identifier of the system error message.

Старайтесь следовать принципу: не более трёх существительных в цепочке и не более одного предлога.

Ошибка 3: Определяющее существительное во множественном числе

Если предыдущие две ошибки были скорее «a matter of style», то эта ошибка — грамматическая. По общему правилу, определяющие существительные всегда стоят в единственном числе. Следите за руками: the list of methods — the method list. Видите, s магически пропадает, хотя методов по-прежнему много. Не ставьте определяющее существительное во множественное число, даже если оно подразумевается.

Иногда это правило приводит к неоднозначности формулировки. Например, словосочетание the table partitions может означать как партиции одной таблицы, так и нескольких. Если из контекста это непонятно и нужно подчеркнуть, что таблица не одна, то просто используйте конструкцию с предлогом: the partitions of tables.

Есть и исключения: если слово употребляется только во множественном числе, либо употребляется в нём чаще, чем в единственном, то и в роли определения оно остаётся во множественном числе. Хрестоматийные примеры, вроде sports shop и ladies room, вряд ли встретятся вам в документации, поэтому вот пример погорячее — cookies. И на самом деле здесь нет единого правильного написания. Многие трендмейкеры, включая Facebook, беззастенчиво использует словосочетание Cookies Policy, хотя Cookie Policy в среднем используется в три раза чаще. В таких случаях вы вольны выбирать, главное — придерживайтесь выбранного варианта.

Также это правило неприменимо, если речь идёт о названии элемента интерфейса или иной программной сущности, т. к. такие названия никогда не видоизменяются. Допустим, в описываемой системе есть список с названием Methods — the Methods list.

Не копируйте русскую пунктуацию

Хотя правила русской и английской пунктуации очень похожи, в них есть ряд расхождений.  Рассмотрим три самых распространённых отличия.

Запятые перед придаточными предложениями

Сравните два предложения:

• Алиса и Боб шифруют сообщения с помощью SSL-протокола, который широко применяется при передаче данных.

• Ева перехватила сообщение, которое Алиса отправила Бобу.

В обоих случаях придаточная часть отделяется запятой и начинается с союзного местоимения «который(-ое)». Но присмотритесь к смысловой нагрузке этих придаточных предложений. В первом случае придаточная часть носит дополняющий характер, и её можно выкинуть без потери смысла предложения, а во втором случае — определяющий. Без неё смысл предложения будет как минимум неполным.

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

• Alice and Bob encode messages using SSL protocol, which is widely applied in data communications.

• Eve has intercepted the message that Alice sent to Bob.

Алгоритм довольно простой: если кусок предложения можно выкинуть без потери смысла — выкиньте используйте запятую и which, если нельзя — используйте that без запятой.

Использовать which вместо that допустимо, сами носители так часто делают, это на полноценную ошибку не тянет. Запятая при этом также не ставится: Eve has intercepted the message which Alice sent to Bob. А вот использовать that вместо which или ставить перед ним запятую — это прям ошибка-ошибка. Не надо так.

Запятые перед союзами but и if

Здесь всё совсем не так однозначно, как с русскими «но» и «если».

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

Союз if, как и его коллега «если», вводит придаточное предложение. В русском языке такое придаточное всегда отделяется от главного запятой. В английском же запятая ставится только тогда, когда придаточное стоит перед главным. 

Таким образом, перед if запятая не ставится почти никогда. Исключение составляют только придаточные из разряда «если вам так хочется»: You can set the parameter to “true”, if you like. Я не рекомендовал бы использовать подобные обороты в документации, но в переписке вполне может пригодится.

Оксфордская запятая

По названию можно подумать, что это очень начитанная, образованная и чопорная запятая. В действительности это просто запятая перед and и or при перечислении трёх и более пунктов: The available extensions are: .txt, .docx, and .xls. Здесь есть вполне обоснованная логика: запятая показывает, что это разные пункты, а не две части единого целого.

Конечно, подобные примеры скорее редкость, и обычно из контекста понятно, что после and перечисление продолжается. Сами носители используют оксфордскую запятую не всегда, это вопрос стиля. Тем не менее айтишные стайлгайды (Google, Microsoft) единогласно рекомендуют использовать её. Используйте, сойдёте за своего.

Не используйте will для описания работы системы

Это самая распространённая ошибка, которую я и сам долгое время допускал.

В школе многих из нас учили, что будущее время, или Future tense, в английском образуется с помощью добавления will. Нас обманули. Правда в том, что в английском толком и нет Future tense, но вместо него есть целый ряд способов говорить о будущем. Добавление will — только один из таких способов, который применяется, чтобы выразить намерение или высокую вероятность события. С полным списком можете ознакомиться здесь, если интересно, а я заострю ваше внимание на одной конструкции.

Рассмотрим фразу на русском: 

Если вы бросите топор в реку, он утонет. 

Здесь оба глагола в будущем времени. Посмотрим, как фраза звучит на английском: 

If you throw an ax in a river, it sinks.

Никакого will. Почему? Да потому что мы констатировали факт! Здесь абсолютно неважно когда произойдёт описываемое действие, и нет никаких сомнений, в том, что выполнение условия приведёт к указанному результату. Если вы бросаете топор в реку — он тонет. Такова природа топора. 

Если написать:

If you throw an ax in a river, it will sink, 

для носителя английского это будет читаться как:

Если вы бросите топор в реку, то он с высокой вероятностью утонет.

Думаю, вы согласитесь, что такого рода предположение здесь неуместно.

Итак, в английском для описания фактов используется простое настоящее время. А описание фактов — это то, из чего на 99% состоит хорошая документация. В ней почти нет места предположениям.

Иногда всё-таки предположения в документации уместны и will необходимо. Но как правило, когда речь идёт не о поведении системы, а о поведении пользователя.

Обратите внимание, что в той части предложения, которая содержит условие, в любом случае используется Present simple.

Вообще все эти условные конструкции называются Conditional Sentences и их целых четыре. Подробнее о них хорошо написано здесь (если вы находитесь в России, используйте VPN). При работе с документацией вам пригодятся только те, что Zero и First, и про них вы только что узнали.

Почитайте что-нибудь ещё

Вместо заключения я посоветую вам пару ресурсов, которые помогут лучше разобраться в грамматике и стилистике английского:

• Grammarly — справочник по грамматике с хорошими пояснениями и примерами. Из России доступен только с VPN.

• Cambridge Dictionary — словарь и грамматический справочник в одном лице. Проверять произношение лучше всего здесь.

• Стайлгайд Гугла для разработчиков — сам за себя говорит. Не истина в последней инстанции, но best practices полезные.

• Стайлгайд Майкрософт — тоже в представлении не нуждается.

Пишите в комментариях, была ли эта статья полезной для вас, и какие сложности испытываете вы. Если у вас возникли вопросы — задавайте, я постараюсь ответить всем.