6. Грамматика и пунктуация

6.1. Общие стили и использование, а также распространённые ошибки

6.1.1. Ansible

• Пишите «Ansible». Не «Ansible, Inc.» или «AnsibleWorks». Единственные исключения — юридические или финансовые документы.
• Никогда не используйте логотип в тексте без контекста. Всегда сохраняйте тот же шрифт, что и в остальной части предложения.
• Компания в США — это единственное число. Другими словами, Ansible — это «оно», а не «они».

6.1.2. Написание с большой буквы

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

6.1.3. Двоеточие

Двоеточие обычно используется перед списком или рядом: — Район Треугольника состоит из трёх городов: Рэли, Дарем и Чапел-Хилл.

Но не если список является дополнением или объектом элемента в предложении: — Перед отъездом в отпуск обязательно (1) установить будильник, (2) отменить доставку газеты и (3) попросить соседа забирать вашу почту.

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

1. Открыть терминал.
2. Ввести cd...

Используйте двоеточие для введения списка с маркерами (или тире, или иконки/символа по вашему выбору):

В диалоговом окне «Свойства» вы найдёте следующие записи:

• Имя подключения
• Количество
• Стоимость за единицу

6.1.4. Запятые

Используйте запятые при перечислении, запятую перед «и» в ряду из трёх или более элементов:

• «Элемент 1, элемент 2 и элемент 3».

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

Запятые всегда важны, учитывая огромную разницу в значениях следующих двух предложений.

• Поедим, бабушка!
• Поедим бабушку!

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

Если это не убедило, возможно, это поможет:

6.1.5. Сокращения

Не используйте сокращения в документации Ansible.

6.1.6. Тире

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

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

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

Upon discovering the errors (all 124 of them), the publisher immediately recalled the books.

Upon discovering the errors—all 124 of them—the publisher immediately recalled the books.

After three weeks on set, the cast was fed up with his direction (or, rather, lack of direction).

After three weeks on set, the cast was fed up with his direction—or, rather, lack of direction.

6.1.7. Восклицательные знаки (!)

Не используйте их в конце предложений. Восклицательный знак может использоваться при упоминании команды, такой как команда bang (!).

6.1.8. Ссылок на пол

Не используйте гендерно-специфические местоимения в документации. Гораздо проще читать предложение с использованием «они» и «их», чем «он/она» и «его/её».

Можно использовать «вы», давая инструкции, и «пользователь», «новые пользователи» и т. д. в более общих объяснениях.

Никогда не используйте «один» вместо «вы» при написании технической документации. Использование «один» слишком формально.

Никогда не используйте «мы» при написании. «Мы» не делаем ничего со стороны пользователя. Продукты Ansible выполняют работу по запросу пользователя.

6.1.9. Дефис

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

Используйте дефисы, чтобы избежать неоднозначности или путаницы:

a little-used car
a little used-car

cross complaint
cross-complaint

high-school girl
high schoolgirl

fine-tooth comb (most people do not comb their teeth)

third-world war
third world war

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

6.1.10. Списка

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

Пишите с большой буквы первое слово каждого маркера. Если не очевидно, что это просто список элементов, например, компьютер * монитор * клавиатура * мышь.

Когда список с маркерами появляется в контексте другого текста (если это не прямой список, как в предыдущем примере), добавляйте точки, даже если маркеры являются фрагментами предложений. Часть причины этого в том, что каждый маркер считается завершением исходного предложения.

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

При предоставлении инструкций используйте нумерованные списки вместо списков с маркерами.

6.1.11. Месяцы и штаты

Сокращайте месяцы и штаты в соответствии с AP. Месяцы сокращаются только если используются вместе с числом. Например: «Президент посетил в январе 1999 года» или «Президент посетил 12 января».

Месяцы: янв., февр., мар., апр., май, июнь, июль, авг., сен., нояб., дек.

Штаты: Аляска, Аризона, Арканзас, Калифорния, Колорадо, Коннектикут, Делавэр, Флорида, Джорджия, Иллинойс, Индиана, Канзас, Кентукки, Луизиана, Мэриленд, Массачусетс, Мичиган, Миннесота, Миссисипи, Миссури, Монтана, Небраска, Невада, Нью-Гэмпшир, Нью-Джерси, Нью-Мексико, Нью-Йорк, Северная Каролина, Северная Дакота, Оклахома, Орегон, Пенсильвания, Род-Айленд, Южная Каролина, Южная Дакота, Теннесси, Вермонт, Вирджиния, Вашингтон, Западная Вирджиния, Висконсин, Вайоминг.

6.1.12. Цифры

Числа от одного до девяти пишутся словами. 10 и выше — цифрами. Исключение — «4 миллиона» или «4 ГБ». Также допустимо использование цифр в таблицах и диаграммах.

6.1.12.1. Номера телефонов

Стиль номера телефона: 1 (919) 555-0123 х002 и 1 888-GOTTEXT

6.1.13. Цитаты (Использование кавычек и написание цитат)

За исключением редких случаев, используйте только «сказал» или «говорит», потому что всё остальное мешает самой цитате, а также склонно к редакторской интерпретации.

Укажите имя сразу после цитаты:

«Мне нравится писать от первого лица, потому что я люблю перевоплощаться в персонажа, которого я пишу», — сказал Уолли Ламб.

Не:

«Мне нравится писать от первого лица, потому что я люблю перевоплощаться в персонажа, которого я пишу», — сказал Уолли Ламб.

6.1.14. Точка с запятой

Используйте точку с запятой для разделения элементов в списке, если элементы содержат запятые:

• Каждый день я пью кофе, ем тост и фрукты на завтрак; салат на обед; и бутерброд с арахисовым маслом, печенье, мороженое и шоколадный торт на ужин.

Используйте точку с запятой перед союзами (например, однако, следовательно, иначе, а именно, например и т.д.): — Я думаю; следовательно, я существую.

6.1.15. Интервал после предложений

Используйте только один пробел после предложения.

6.1.16. Время

• Время суток записывается как «16:00».