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

Привет, Хабр! Я работаю техническим писателем в компании documentat.io, мы занимаемся заказной разработкой технической документации, в том числе на английском языке.

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

В этой статье разберём другую разновидность подводных камней английского — двусмысленные конструкции. Даже носители языка иногда упускают их из виду. А ведь любое двусмысленное выражение может затруднить понимание текста, особенно для пользователя, который только начинает разбираться в предмете. Каждая запинка при чтении приближает пользователя к тому, чтобы бросить документацию и пойти дёргать техподдержку или писать про продукт гадости в интернете. Таким образом, двусмысленность в конечном счёте может стоить бизнесу денег.

Неопределившиеся определители

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

❌ The field contains the system error message text identifier
✅ The field contains the text identifier of the system error message

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

❓ It is convenient to use the analytics system log viewer
✅ It is convenient to use the viewer of the analytics system log
✅ It is convenient to use the log viewer that is the part of the analytics system

Обе интерпретации в теории имеют смысл, а значит, перефразируя закон Мёрфи: если что-то можно понять неправильно, кто-то это поймёт неправильно.

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

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

 — А зачем нам эти бесполезные восемь падежей? Выкинем этот хлам, оставим только два.
— И как же мы теперь будем определять, что к чему относится?
— Ну так, примерно почувствуем.

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

❓ The method returns new resume views Здесь непонятно, относится ли new к резюме или к просмотрам? Починить такого рода проблему можно старым добрым добавлением предлогов и артиклей: ✅ The method returns new views of the resume ✅ The method returns views of the new resume Будьте бдительны со словом new, оно часто приводит к подобным двояким трактовкам.

❓ Satellite information Это информация со спутника или о спутнике? Проблема в том, что без контекста бывает непонятно, как именно определяющее существительное относится к основному, т. е. через какой предлог это можно переформулировать: for, of, by, about, from и т. д. Чинится явным указанием предлога: ✅ Information from a satellite ✅ Information about a satellite

❓ Sample requests are listed below Двусмысленность этого примера многие англоязычные авторы из IT, кажется, не замечают. Он часто встречается в контексте API и не вызывает вопросов у разработчиков. Но я знаю случай, когда переводчик, который недостаточно хорошо понимал предметную область, попал в ловушку. Проблема в том, что определяющее слово sample может отвечать на разные вопросы: 🔷 Sample requests — запросы (чего?) образца(-ов). 🔷 Sample requests — запросы (какие?) образцовые, типовые. Если в тексте имеется в виду первый случай, то неоднозначность можно устранить предлогом: ✅ Requests for samples are listed below Если же имеется в виду второй случай, то предлог тоже сработает, но для айтишного уха получится немного неестественно: ☑ Samples of requests are listed below К счастью, в данном примере можно поменять слова местами без потери смысла: ✅ Request samples are listed below Обошлось без предлогов, читается однозначно и узнаваемо. Лично я считаю, что лучше всегда использовать этот вариант, даже если гугл или Том Джонсон со мной не согласятся.

❓ Multiple value parameters Это параметры, которые могут принимать несколько значений, или это несколько value parameters? В первом случае однозначность словосочетанию можно придать при помощи дефиса, не обязательно мучиться с предлогами: ✅ Multiple-value parameters Во втором случае можно раскрыть термин value parameters: ✅ Multiple parameters that are passed by value Но в некоторых случаях не стоит трогать термины, с ними вообще нужно бережно. Об этом в следующем примере.

✅ Virtual network adapter Это словосочетание двусмысленно. Его можно понять как виртуальный адаптер для сети (это он и есть) или адаптер для виртуальной сети (таких не существует, но всё же понять так можно). Тем не менее изменять это словосочетание не нужно. Virtual network adapter — это распространённый профессиональный термин. Если вы его измените, то специалисты решат, что вы не владеете терминологией. Это снизит их доверие и к тексту, и к продукту. Не ломайте термины, чтобы починить двусмысленность. А чтобы новичок или неопытный переводчик не решил, что речь про адаптер для виртуальной сети, давайте терминам определения. Для этого можно завести глоссарий, либо приводить определения прямо в тексте.

Коварные союзы

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

Допустим, мы хотим передать на английском какую-нибудь несложную мысль вида: RU Службы мониторинга используют системные и диагностические данные. Допустим, мы не паримся и переводим с русского дословно: ❓ The monitoring services use system and diagnostic data. Из-за того, что в английском нет окончаний и разные части речи могут выглядеть одинаково, появилась неоднозначность. Читатель может решить, что system — это отдельный объект (use [system] and [diagnostic data]), хотя мы-то знаем, что это определитель для data. Самый простой способ устранить неоднозначность в этом случае — повторить основной объект: ✅ The monitoring services use system data and diagnostic data. Если повторение слова выглядит некрасиво, попробуйте переформулировать предложение целиком. Например, поставьте основной объект вперёд:  ✅ The monitoring services use data from system sensors and diagnostic utilities.

❓ You can use standard library or program script. Какие слова соединяет союз or в данном примере — library и script или use и program? Уверенно ответит только автор предложения. Такая проблема в английском называется двусмысленной сочинительной связью (ambiguous scope of conjunction) — когда непонятно, какие части предложения соединяются союзами and и or. Полечить такую связь в большинстве случаев можно повторением вспомогательных частиц, правильной расстановкой артиклей или сменой порядка связываемых слов. Вернёмся к примеру. Корень проблемы здесь в том, что в предложении непонятна роль слова program, поэтому пример вполне лечится добавлением артикля в нужном месте (см. первую статью): ✅ You can use a standard library or program a script. ✅ You can use a standard library or a program script. А что, если script тоже подразумевается standard? Напишите об этом явно: ✅ You can use a standard library or a standard program script.

А как быть, если существительные требуют нулевого артикля? ❓ You can use standard libraries or program scripts. Определите источник двусмысленности и перенесите его ближе к глаголу. Мы уже выяснили, что в этом примере источником двусмысленности является слово program. Посмотрим, как это работает: ✅ You can use program scripts or standard libraries. ✅ You can program scripts or use standard libraries.

Confus-ing

— Наконец мы избавились от эти глупый падежи. Пришёл пора убрать разный суффиксы для причастие и герундий. Теперь все суффиксы будут -ing. Меньше суффиксы запоминать будем.
— Но у мы же ещё прилагательные и существительные есть, который на -ing заканчиваются. Как мы будем всё это различать?
— Да как-нибудь разберёмся через контекст, не душни.
(с) Средневековые англичане

Ещё немного расслабимся и насладимся примером «разнообразия» грамматических форм в английском. Посмотрим, какую роль в предложении может играть слово, оканчивающиеся на -ing — инговое слово.

I am writing a Habr article	Я пишу статью для Хабра (я есть пишущий)	Причастие
Writing can be difficult but rewarding activity	Процесс написания может быть сложным, но приносит удовлетворение	Герундий
I try to make my writing easy to read	Я стараюсь, чтобы написанное легко читалось (моя писанина)	Существительное
But it is a real mess on my writing desk	Но на моём письменном столе полный бардак	Прилагательное

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

Но есть ситуации, когда плавающая грамматическая роль инговых слов может приводить к проблемам, being confusing:

Когда инговое слово стоит перед существительным, его иногда можно интерпретировать и как герундий, и как причастие или прилагательное: ❓ The product is designed for certifying staff. Если certifying это герундий, то предложение можно прочитать так: ✅ The product is designed to certify staff. Если certifying прилагательное: ✅ The product is designed to be used by certifying staff. Заодно мы и нашли, как такое предложение можно починить. Ниже есть ещё способы.

Когда инговому слову предшествует несколько существительных, не всегда бывает понятно, к какому из них оно относится.  ❓ The following example shows a config block specifying that the items be sorted by name. Лечится также перефразированием: ✅ In the following example, a config block specifies that the items be sorted by name. ✅ The following example shows a config block. The items in this example are sorted by name.

❓ ❌ If an error occurred while updating a config file, the operating system might be able to recover the file. Используя герундий после некоторых слов, он может оказаться не связан с субъектом предложения. Да, прямо как тут деепричастие используя. Эта грамматическая ошибка в английском называется dangling gerund и встречаются даже у носителей. Чаще всего она возникает, когда герундий стоит после after, before, by, prior to, since, until, when или while. Будьте особенно внимательны в таких случаях. В этом примере словосочетание while updating потеряло своего субъекта — того, кто выполняет обновление конфиг-файла. Хотя формально грамматическим субъектом выступает ошибка: ❌ If an error occurred while the error is updating a config file, the operating system might be able to recover the file. Конечно, это полная чушь, и читатель невольно отправится на поиски более подходящего субъекта. В предложении есть операционная система, она подходит: ❌ If an error occurred while the operating system is updating a config file, the operating system might be able to recover the file. Но это тоже неверно. Устранить двусмысленность в такой ситуации поможет только явное указание субъекта действия: ✅ If an error occurred while you are updating a config file, the operating system might be able to recover the file. Можно ли сделать это предложение ещё лучше? Напишите в комментариях.

Если с ингового слова начинается название раздела или короткая подпись, установить его грамматическую роль можно только из контекста. ❓ Defining Characteristics Глава с таким названием описывает процесс определения характеристик или характеристики, которые что-то определяют? ❓ Stabilizing Cycles Это процесс стабилизации циклов или циклы стабилизации чего-то? В таких случаях вам придётся смириться с двусмысленностью в названии. Главное — придерживайтесь одного значения во всей документации. Иногда на помощь могут прийти артикли: Stabilizing the Cycles/The Stabilizing Cycles, но только если их применение оправдано по смыслу и допустимо грамматически. О правильном применении артиклей читайте в первой статье.

Общие лечебные рекомендации

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

Попробуйте привести фразу к такому виду, в котором инговые конструкции никогда не бывают двусмысленными: 🔷 -ing + артикль/прил. + сущ. (всегда герундий) ✅ Defining a specimen characteristics. 🔷 артикль/прил. + -ing + сущ. (всегда определение) ✅ The main defining characteristics. 🔷 -ing + сущ. во мн. ч. + форма to be (определение или герундий в зависимости от формы to be) ✅ Defining characteristics is a complicated process. ✅ Defining characteristics are listed in the table below.

Если инговое слово следует за существительным и служит ему определением, замените это инговое слово на that + глагол: ❓ Set characteristics defining performance. ✅ Set characteristics that define performance. Этот приём неприменим, если инговое слово не служит определением к существительному, после которого стоит: ❓ Set performance defining characteristics. ❌ Set performance that defines characteristics. В таких случаях устраните двусмысленность другими средствами: ✅ Set performance by defining characteristics. ✅ Set performance-defining characteristics.

Если герундий следует за глаголом, то в некоторых случаях его можно заменить на to + inf. Но такую замену нельзя выполнять не глядя, есть правила: 🔷 Заменить герундий на to + inf можно смело, если он следует за глаголами: begin, start, continue, intend, cease, dread или love. Если последний понадобится вам в документации, то я вам завидую, вероятно, вы пишете инструкцию по эксплуатации котэ. ❓ The system starts defining characteristics. ✅ The system starts to define characteristics. 🔷 Если герундий следует за глаголами advise, recommend, allow, permit, forbid или require, то при замене на to + inf укажите «адресата» действия: ❓ The policy forbids deleting methods. ✅ The policy forbids users to delete methods. В остальных случаях такая замена либо грамматически недопустима, либо изменит смысл предложения: 🔷 The system stops defining characteristics — Система остановила процесс определения характеристик. 🔷 The system stops to define characteristics — Система остановилась, чтобы определить характеристики.

В попытке починить двусмысленность инговой фразы, вы можете попробовать заменить инговое слово на отглагольное существительное, например stabilizing на stabilization. Это тонкий лёд. Скорее всего, вы получите несколько иной смысл, так как инговое слово относится к процессу, а отглагольное существительное — к результату: 🔷 Stabilizing is initiated by the system. 🔷 Stabilization is achieved. А можете и опозориться: 🔷 Archiving — это процесс перемещения в архив. 🔷 Archivation — не существует в английском.

Что ещё почитать, посмотреть

Вместо заключения традиционно порекомендую интересного:

🔷 Первую часть этой трилогии и все ресурсы, которые я рекомендовал там.
🔷 The Global English Style Guide, автор John R. Kohl. Если бы я мог выбрать всего один стайлгайд по англоязычной документации, я бы выбрал его.
🔷 YouTube-канал Арно Тали. Чувак понятно и смешно рассказывает о разных фичах английского и истории его развития.

А если вам нужна готовая качественная документация для вашего продукта, доверьте это documentat.io.

Автор: Костя Макушев
Редактор: Ната Мелихова