Как написать понятное руководство: стандарты и лучшие практики

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

Часть 1: Типы руководств

Полное руководство (Comprehensive Guide)

Подробное описание от А до Я. Объём: 3 000–10 000+ слов. Модульная структура с навигацией. От новичков до продвинутых пользователей.

HOW-руководство (Task-based Guide)

Ответ на вопрос «Как сделать X?» Объём: 800–2 500 слов. Фокус на одном действии. Минимум теории, максимум практики.

Часть 2: Подготовка

Матрица уровней подготовки аудитории

Чек-лист перед написанием

• Определена целевая аудитория (уровень знаний, боли, цели)
• Выбран тип руководства (полное vs HOW-to)
• Сформулирована конечная цель читателя
• Проведён анализ конкурентов (топ-5 выдачи)
• Подготовлены инструменты для скриншотов/визуала

Часть 3: Универсальная структура HOW-гайда

1. ЗАГОЛОВОК (конкретный, с обещанием результата)
2. ВСТУПЛЕНИЕ (2-3 предложения: что и для кого)
3. ЧТО ПОНАДОБИТСЯ (инструменты, доступы, время)
4. ПОШАГОВАЯ ИНСТРУКЦИЯ
   4.1 Шаг 1 ...
   4.2 Шаг 2 ...
5. ВОЗМОЖНЫЕ ПРОБЛЕМЫ И РЕШЕНИЯ
6. РЕЗУЛЬТАТ (фото/описание конечного состояния)
7. ССЫЛКИ ПО ТЕМЕ

Часть 4: Правила оформления

• Абзацы: максимум 5-6 строк, одна мысль = один абзац.
• Заголовки: H1 — один, H2 — разделы, H3 — подразделы.
• Списки: нумерованные — для шагов, маркированные — для перечислений.
• Таблицы: для сравнений, настроек, тарифов.
• Принцип «сухого текста»: убирайте вводные конструкции, заменяйте пассив на актив, удаляйте очевидные утверждения.

Tone of Voice

Часть 5: Визуальный контент

Типы визуализации

Стандарты изображений

• Формат: PNG (скриншоты), JPEG (фото), WebP (web).
• Разрешение: минимум 1200px по широкой стороне.
• Размер файла: до 300KB.
• Нумерация и подписи под каждым изображением.
• Акценты: стрелки, рамки, выделение для критических элементов.

Часть 6: Чек-лист качества

Содержание

• Заголовок отражает суть и обещает результат
• Все шаги логически связаны
• Нет пропущенных промежуточных действий
• Указано время выполнения
• Есть предупреждения о рисках
• Показан ожидаемый результат

Текст

• Удалены вводные слова и клише
• Абзацы ≤ 6 строк
• Термины объяснены (для новичков)
• Проверены орфография и пунктуация

Визуал

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

Тест на живом человеке

Дайте руководство человеку, не знакомому с темой. Он должен достичь цели без вашей помощи. Где спросил, заколебался, ошибся — там и дорабатывайте.

Часть 7: 20 ляпов в технических документах

1. Первое упоминание аббревиатуры — полностью. «Техническое задание (далее — ТЗ)», а не сразу «ТЗ».

2. Однообразие названий. Либо везде «Система» с прописной, либо везде со строчной.

3. Падежи. Склоняйте, пожалуйста.

4. Версии ПО везде одинаковы. Не «MS Internet Explorer 8+» в одном месте и «Microsoft IE 8.5» в другом.

5. Используйте русские названия элементов интерфейса. Не «прогрессбар», а «индикатор выполнения».

6. Тире ≠ дефис. Тире — длинная чёрточка между словами с пробелами.

7. Дефис ≠ тире. Дефис — короткая чёрточка без пробелов.

8. Формулируйте однообразно. Если используете «должно» — забудьте «нужно» и «необходимо».

9. Активный залог. «Система должна отображать окно» вместо «Должно отображаться окно».

10. Единый стиль списков. Если маркер уровня 1 — чёрточка, то везде чёрточка.

11. Пунктуация в списках. Соблюдайте правила.

12. Единицы измерения — без точки. «кг», а не «кг.».

13. «Чтобы» ≠ «что бы».

14. «Также» ≠ «так же».

15. Причастный оборот после определяемого слова — запятыми.

16. Деепричастный оборот — всегда запятыми.

17. Не употребляйте кванторы общности. «Все», «каждый», «никто», «всегда», «никогда» — требование либо невыполнимо, либо неоднозначно.

18. Не завершайте списки «и т.д.», «и прочие». Фиксируйте конкретный перечень.

19. Избегайте причастий, не уточняющих требование. «Данные в согласованном формате» — кем согласованном? Когда?

20. Единый шрифт. Если нет особой необходимости — не смешивайте Times New Roman с Arial.