3. Основные правила

3.1. Использование стандартного американского английского

Компания Ansible имеет клиентов/пользователей по всему миру, но штаб-квартира расположена в Дареме, Северная Каролина, США. Используйте стандартный американский английский, а не другие варианты английского языка.

3.2. Написание для глобальной аудитории

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

3.3. Соблюдение соглашений об именовании

Всегда соблюдайте соглашения об именовании и товарные знаки. Если вы не уверены, как правильно называть продукт, обратитесь к менеджеру по продуктам отдела Инженерии этого продукта (ansible-core или Tower) за информацией.

3.4. Важная информация в первую очередь

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

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

Более понятно: Опасно! Держитесь подальше от обрыва.

3.5. Структура предложений

Хорошая структура предложения помогает передать информацию. Постарайтесь расположить наиболее важную информацию в начале предложения.

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

Лучше: Для извлечения также требуется большое количество воды.

3.6. Избегайте добавления лишней информации

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

3.7. Избегайте избыточных предложных оборотов

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

3.8. Избегайте многословия

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

3.9. Избегайте высокопарности

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

3.10. Глаголы действия, меню и команды

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

Наиболее часто используемые глаголы в программном обеспечении:

• Нажать
• Дважды щелкнуть
• Выбрать
• Ввести
• Нажать

Использование глагола действия в предложении (**выделенные** слова):

1. В диалоговом окне нажмите **Открыть**.
2. **Введите** имя в текстовое поле.
3. На клавиатуре нажмите **Ввод**.

Использование действий меню и команд в предложении:

1. В меню **Файл** нажмите **Открыть**.
2. **Введите** имя в поле **Имя пользователя**.
3. В диалоговом окне **Открыть** нажмите **Сохранить**.
4. На компьютерной клавиатуре нажмите **Ввод**.
5. На панели инструментов нажмите значок **Открыть файл**.

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