Руководства по стилю

Языковой стандарт: en-US

Случай использования: SaaS B2B продукт – Справочный центр и пользовательский интерфейс

# Руководство по стилю: EN-US – Статьи справочного центра

## 1. Цель и область применения

Это руководство по стилю определяет стандарты написания для всей **документации справочного центра** на **английском (США)**.

Оно применяется к:

- Статьям с инструкциями  
- Объяснениям функций  
- Руководствам по устранению неполадок  
- Записям часто задаваемых вопросов  

**Аудитория:** профессиональные пользователи SaaS в технических и бизнес-ролях  
**Цель:** помочь пользователям быстро, уверенно и без путаницы выполнять задачи.

---

## 2. Голос и тон

Контент справочного центра должен звучать:

- **Ясно и профессионально**
- **Поддерживающе и ориентированно на решение**
- **Уверенно, но не рекламно**

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

### Принципы тона

| Делать | Не делать |
|---|------|
| Будьте спокойны и прямолинейны | Не будьте слишком неформальными или болтливыми |
| Сосредоточьтесь на следующих шагах | Сосредоточьтесь только на том, что пошло не так |
| Используйте нейтральный язык | Используйте сарказм или юмор |

**Примеры**

- ✅ "Если соединение не удается, проверьте ваш токен API и попробуйте снова."  
- ❌ "Ваш токен неверен. Исправьте это." ## 3.

---

## 3. ### 3.1 Обращайтесь к читателю напрямую

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

- ✅ "Вы можете управлять пользователями со страницы администратора."

- ❌ "Пользователями можно управлять со страницы администратора."  
### 3.2 Предпочитайте активный залог

---

Активный залог короче и легче для восприятия.

- ✅ "Выберите **Сохранить изменения**."

- ❌ "Сохранить изменения должно быть выбрано."  
### 3.3 Держите предложения краткими

---

- Стремитесь к **25 словам или меньше**

- Одна основная идея на предложение
 
- Разбейте длинные объяснения на шаги или пункты

---

### 3.4 Используйте простой язык

Избегайте ненужной сложности.

- ✅ "Начните новый проект."  
- ❌ "Инициируйте создание нового проекта."

---

## 4. Терминология и последовательность

### 4.1 Используйте утвержденные термины

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

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

**Пример**

- ✅ "рабочее пространство"  
- ❌ "пространство," "проектная область," "среда"

---

### 4.2 Определите редкие аббревиатуры

Общие термины (API, URL) не требуют определения.  
Внутренние или редкие аббревиатуры должны быть объяснены при первом использовании.

- ✅ "Единый вход в систему (SSO)"  
- ❌ "SSO" без контекста

---

### 4.3 Конвенции американского английского

Всегда используйте **американское написание**.

- ✅ “настраивать,” “поведение”  
- ❌ “настраивать,” “поведение”

---

## 5. Стандарты форматирования и Markdown

### 5.1 Заголовки

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

- ✅ “Сбросьте ваш пароль”  
- ❌ “Обзор процесса сброса пароля”

Иерархия заголовков:

- `#` Заголовок статьи  
- `##` Основные разделы  
- `###` Подразделы только при необходимости  

---

### 5.2 Списки

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

1. Откройте **Настройки**  
2. Выберите **Биллинг**  
3. Выберите **Изменить план**  

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

- Администраторы могут управлять пользователями  
- Редакторы могут обновить контент  

---

### 5.3 Элементы интерфейса

Форматируйте метки интерфейса последовательно:

- Кнопки: **жирный**
- Навигационные пути: используйте стрелки

Пример:

Перейдите в **Настройки → Платежи → Изменить план**.

---

### 5.4 Ссылки

Ссылки должны описывать назначение.

- ✅ "Смотрите руководство по выставлению счетов"  
- ❌ "Нажмите здесь"

---

## 6. Стандартная структура статьи

Каждая статья в Справочном центре должна следовать этой структуре:

### 1. Сводная информация

Начните с 1–2 предложений, объясняющих результат.

> Эта статья объясняет, как изменить ваш план подписки.

---

### 2. Предварительные условия (необязательно)

Укажите требования заранее.

- Права администратора  
- Активная подписка  

---

### 3. Пошаговые инструкции

Этапы должны быть:

- Ориентированные на действие  
- Одно действие на этап  
- Написаны в виде команд  

Пример:

1. Перейдите в **Настройки**.  
2. Выберите **Биллинг**.  
3. Выберите **Изменить план**.  

---

### 4. Ожидаемый результат

Сообщите пользователю, что должно произойти.

> Ваш новый план вступает в силу немедленно после подтверждения.

---

### 5. Следующие шаги (по желанию)

Предоставьте связанные действия или ссылки.

- Управление счетами  
- Обновить способ оплаты  

---

## 7. Устранение неполадок и ошибки

### 7.1 Будьте уверены

- ✅ "Мы не смогли подключиться." Пожалуйста, попробуйте еще раз."  
- ❌ "Ошибка подключения." Критическая ошибка."

---

### 7.2 Сосредоточьтесь на решениях

Всегда указывайте, что пользователь должен сделать дальше.

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

---

### 7.3 Никогда не обвиняйте пользователя

Избегайте языка, как:

- "Вы сделали что-то неправильно"  
- "Неверный ввод" (без объяснения)

Предпочтительный:

> "Токен может быть просрочен." Сгенерируйте новый и повторите попытку."

---

## 8. Сводка "Делать / Не делать"

### Делать

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

### Не делать

- Добавляйте маркетинговый язык  
- Используйте идиомы или сленг  
- Смешивайте термины для одного и того же понятия  
- Вините пользователя при устранении неполадок  
- Пишите длинные абзацы без структуры  

---

## Пример (Предпочтительно)

Чтобы изменить ваш план:

1. Перейдите в **Настройки → Платежи**  
2. Выберите **Изменить план**  
3. Выберите вариант и нажмите **Подтвердить**