Привет, Хабр!

Продолжаю делиться с вами опытом написания документации на английском. Напомню о предыдущих сериях:

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

• Вторая часть — о двусмысленных конструкциях, которые часто встречаются в документации и которые легко упустить из виду.

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

Зачем это нужно?

Мировая статистика говорит, что английским владеет примерно 1,4 миллиарда человек, но носителей среди них всего 380 миллионов. То есть статистически семь из десяти читателей англоязычной документации — не носители языка.

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

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

Восстание машин

Конечно, первое что сделает современный пользователь со слабым английским — засунет доку в условный Google Translate. Это решит проблему, но лишь отчасти. Качество машинного перевода всё ещё сильно зависит от исходного текста.

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

❓ Do not dip your bread or roll into your soup.
❌ Не макайте хлеб и не катайте его в суп.

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

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

Ошибки машинного перевода можно свести к минимуму, если следовать некоторым рекомендациям. В нашем примере достаточно избавиться от двусмысленности, чтобы Google нас понял:

✅ Do not dip your bread or your roll into your soup.
✅ Не макайте хлеб или булочку в суп.

Что же делать?

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

Обойтись без слов

Самый радикальный способ — не писать документацию, а рисовать её. Обойтись вообще без слов. Так тоже можно, если специфика продукта позволяет, производители мебели и Lego не дадут соврать. Например, недавно наткнулся в сети на историю про то, как одна девушка сделала для своей бабушки вот такую книжку с инструкциями к смартфону:

Писать упрощённым английским

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

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

• Ввели строгие грамматические и стилистические правила, которые, например, банят многие формы глагола, включая инговую.

• Составили словарь утверждённых слов. Для каждого слова в словаре прописана его часть речи и утвержденный смысл. Например, слово test является утвержденным существительным, и по правилам STE его нельзя использовать как глагол:

  ? Test the system for leaks.
  ✅ Do the leak test of the system.

  А утверждённый глагол wear должен означать износиться от истирания и ничто другое:

  ? Wear protective clothing.
  ✅ Use protective clothing.
  ✅ The cable can wear quickly in this position.

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

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

Использовать Global English

Я намеренно не перевожу этот термин как «международный английский», чтобы не путать его с International English. Здесь речь пойдёт о конкретном подходе, который подробно описан в книге Джона Коля The Global English Style Guide. Вот определение оттуда:

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

Цели этих рекомендаций:

• Устранить двусмысленность, которая усложняет перевод, в том числе машинный.

• Устранить сложные слова и необычные грамматические конструкции, которые могут быть непонятны неносителям английского.

• Сделать структуру предложений более явной и простой для анализа неносителями.

В отличие от STE, который вводит список разрешённых грамматических конструкций и терминов, рекомендации Global English содержат список нежелательных. Из-за отсутствия строгих ограничений придерживаться Global English не так сложно, а написанный таким языком текст будет звучать естественно для носителей.

Рекомендации Global English

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

Если выразить эти рекомендации одной фразой, она будет звучать так:

Добивайтесь, чтобы структура каждого предложения была простой и синтаксически явной.

Дальше разберёмся, как же этого добиться.

Значком ? обозначены примеры, неошибочные с точки зрения английского в целом, но нежелательные с точки зрения Global English. Значком ✅ — варианты, которые отвечают принципам Global English.

• Старайтесь разбивать длинные и сложные предложения на короткие и простые. Такие предложения намного проще воспринимаются как читателями, так и машинными переводчиками.
  
  ? Contemporary usage of the term API often refers to web APIs, which allow communication between computers that are joined by the internet.
  ✅ Contemporary usage of the term API often refers to web APIs. Web APIs allow communication between computers that are joined by the internet.

• Используйте синтаксические указатели, чтобы сделать структуру предложения более явной.

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

  В повести «Алиса в Зазеркалье» Люиса Кэррола есть стихотворение Jabberwocky (Бармаглот), которое начинается так: Twas brillig, and the slithy toves Did gyre and gimble in the wabe; Все слова кроме служебных здесь вымышлены. Трюк в том, что служебных слов — синтаксических указателей — достаточно, чтобы понять, какую роль в предложении играют вымышленные слова. Так, артикль the однозначно говорит нам, что slithy toves — это группа существительного. А вспомогательный глагол did указывает, что gyre and gimble — глаголы. Если вы знаете аналогичный прикол на русском, напишите в комментариях :)

  Про порядок слов и про то, как правильно использовать артикли и пунктуацию с союзами that и which, я писал в первой статье. Обязательно прочитайте её. Ещё немного о that и which в следующем пункте.

• Вы вероятно знаете, что союзы that и which часто можно опустить. Некоторые стайлгайды даже рекомендуют это делать. Так вот, не делайте этого. Эти предлоги служат синтаксическими указателями и помогают сделать структуру предложения более явной. Используйте их везде, где можно:

  ? The file you specified does not exist.
  ✅ The file that you specified does not exist.

  ? The system determines files you need to check.
  ✅ The system determines files that you need to check.

  ? The algorithm used for the encryption is shown below.
  ✅ The algorithm that is used for the encryption is shown below.

  ? This algorithm, proposed in 1946, is also known as Monte Carlo method.
  ✅ This algorithm, which was proposed in 1946, is also known as Monte Carlo method.

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

• Старайтесь не использовать пассивный залог. Чтобы от него избавиться, определите действующее лицо и поставьте его вперед:

  ? The results that are returned by the query can be viewed using a text editor.
  ❓  You can view the results that the query returns using a text editor.

  Можно ещё лучше, заодно избавимся от возникшей двусмысленности:

  ✅ To view the results that the query returns, use a text editor.

  Если делать акцент на действующее лицо нежелательно, то пассивный залог можно и оставить:

  ✅ The C value was obtained by multiplying A by B.
  ? We obtain the C value by multiplying A by B.

• Где возможно, заменяйте связку вспомогательный глагол+отглагольное существительное на глагол.
  
  ? The following table provides an explanation of the concept.
  ✅ The following table explains the concept.
  
  ? The program enables the encryption of user IDs and passwords.
  ✅ The program encrypts user IDs and passwords.

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

• Используйте простую лексику. Конечно, это не относится к профессиональным терминам, но вместо слов уровня С1, типа substantial, всегда лучше использовать слова уровня А2, типа big или important. Еще пара примеров:
  
  ? Press Apply to initiate the process.
  ✅ Press Apply to start the process.
  
  ? You must de-energize the circuit swiftly.
  ✅ You must immediately turn off the power.

  В общем, как говорил Марк Твен:
  Don’t use a five-dollar word when a fifty-cent word will do.

• Вместо фразовых глаголов используйте их обычные аналоги:
  
  ? Use the algorithm to figure out the source of the problem.
  ✅ Use the algorithm to determine the source of the problem.
  
  Если заменить фразовый глагол не удаётся, держите части фразового глагола вместе:
  
  ? Turn the computer off.
  ✅ Turn off the computer.

• Старайтесь использовать глаголы в Present Simple.

  В документации Future Tense почти всегда можно заменить на Present Simple:

  ? Make tests to determine settings that will result in the best performance.
  ✅ Make tests to determine settings that result in the best performance.

  Исключение — когда действие и правда произойдёт в будущем:

   ✅ You cannot predict which file will be deleted first.

  Подробнее об использовании will читайте в первой статье.

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

  ? If the X option had been specified in general settings, then it would not have been necessary to specify the Y option for every instance.
  ✅ If you specify the X option in general settings, then you do not need to specify the Y option for every instance.

• Если в предложении два и более существительных, осторожно используйте местоимения, в особенности it и its. Не всегда очевидно, к какому именно существительному относится местоимение. Чтобы это пофиксить, повторите существительное целиком:

  ? Once you apply Diataxis to your documentation, writing it is easier.
  ✅ Once you apply Diataxis to your documentation, writing the documentation is easier.

  ? If you place a backslash before a special symbol in a regex, its meaning becomes literal.
  ✅ If you place a backslash before a special symbol in a regex, the symbol meaning becomes literal.

  О других формах двусмысленности и о том, как с ними бороться, читайте в предыдущей статье.

Вместо заключения

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

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

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

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

ⓒ Антуан де Сент-Экзюпери

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