Перевод статьи «Plain English for Everyone».
От редакции Techrocks. Хотя эта статья не ориентирована конкретно на программистов, мы считаем, что советы из нее будут полезны и разработчикам. Прежде всего, они позволят вам улучшить качество вашей документации в проектах. И даже если в ваших компаниях есть отдельные специалисты по написанию документации, не стоит забывать и о своих личных проектах. Выводя свои приложения на рынок, вы в любом случае будете писать к ним описания и инструкции.
Также вам наверняка случится задавать вопросы на специализированных форумах и отвечать на них.
Во всех этих случаях пригодится знать особенности современного английского и уметь строить текст так, чтобы он был понятен как можно большему числу людей.
Кроме того, хотя в статье говорится об английском языке, приведенные советы, в принципе, применимы и для любого другого языка.
Под выражением «простой английский язык» следует понимать понятный и лаконичный английский.
Техническое писательство отличается от художественного. Цель технической документации — сделать сложную техническую информацию легкой для понимания. Поэтому простой английский — это важный аспект технического писательства. Благодаря его использованию ваши тексты будут более доступными, краткими и читаемыми.
Почему простой английский?
- Для множества людей английский — не родной язык. Но из тех, кто его знает, куда больше людей способны понять простой вариант языка, чем сложный.
- Простой английский легче переводить. Обычные, обиходные английские слова и фразы с большей вероятностью будут иметь точные аналоги в других языках.
- Простой английский проще понять. Читатель сможет сконцентрироваться на технических концепциях, а не на расшифровке предложений.
Основы простого английского
Точки вместо запятых
По возможности используйте короткие предложения.
Избегайте комбинирования больше чем двух предложений при помощи запятых.
Отдавайте предпочтение активному залогу
Например, лучше написать
«X() reads a new file»
(«Х() читает новый файл»),
а не
«A new file is read by X()»
(«Новый файл считывается Х()»).
Убирайте прилагательные
Большая часть прилагательных не несут полезной информации. Например, предложение
«This well-written function reads a new file»
(«Эта хорошо написанная функция читает новый файл»)
можно без проблем сократить до
«This function reads a new file»
(«Эта функция читает новый файл»).
Старайтесь как можно быстрее добраться до сути и не отклоняться от темы.
Инклюзивный язык и предрассудки
Старайтесь вообще не использовать местоимения. Если без этого не обойтись,
- используйте «they» вместо «he» или «she», а также
- «folks», «people», «everyone» вместо «girls» или «guys».
Примечание редакции Techrocks к приведенным выше советам:
- В статьях на английском довольно часто (и все чаще) используется местоимение «они». Примерами могут послужить предложения типа «Если пользователь хочет …, он должен …». Вот это «он» в английском чаще всего заменяется на «они», иногда на «она».
- В оригинале статьи есть ссылка на страницу heyguys.cc, где поясняется, чем плохо использование «guys» и «girls». «»Hey guys» («привет, ребята») — это распространенное приветствие, но оно не является гендерно нейтральным. Оно обращено к мужчинам или парням, а все остальные могут почувствовать себя исключенными из этой группы, хотя у говорящего таких намерений могло и не быть». Поэтому лучше говорить (и писать) «привет всем», «привет, народ», «привет, друзья» и т. п.
Избегайте слов, которые можно истолковать в расистском ключе («blacklist», «master», «slave» и т. п.).
Старайтесь не использовать фразы типа «это просто, надо всего лишь…», «этот шаг очень прост» и т. п. То, что просто для одного человека, может быть совсем не просто для другого. Давайте не раздражать читателя подобными выражениями.
Активно ищите проявления предрассудков в своих текстах. Даже подбор имен в примерах (в зависимости от контекста) может задевать какие-то группы людей. Вероятно, мы никогда не сможем быть совершенно непредвзятыми, но стоит постараться.
Избегайте жаргонизмов, используйте общепонятные слова
В технической документации и без того полно сложных терминов. Не нужно усложнять ее еще больше. Хороший способ уменьшить количество жаргонизмов — дать вычитать текст разным людям.
Имейте в виду, что сленг это тоже жаргон.
Дополнительные советы
Планирование
Хорошая практика — составлять план своего документа перед тем как начать его писать. Обдумайте следующие моменты:
- какая у вас целевая аудитория?
- каким должен быть размер документа?
- каков более широкий контекст?
Структура
Начните с примерного наброска структуры. Затем попытайтесь выделить каждую концепцию в отдельный раздел. Четкая структура и заголовки улучшают читаемость.
Руководства по стилю
Руководства по стилю это стандарты, помогающие поддерживать единообразие документации. Старайтесь придерживаться какого-то определенного стиля при написании технических текстов, даже если пишете для собственного блога.
[customscript]techrocks_custom_after_post_html[/customscript]
[customscript]techrocks_custom_script[/customscript]