Кто должен использовать её?

Всегда сначала спрашивайте: Кто будет пользоваться руководством и что они должны уметь делать после того, как закончат с ним работать?

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

Какой это документ?

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

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

Разделы руководства

Как написать шаг

Правила основаны на стандартах для инструкций по эксплуатации и документации пользователя (МЭК/ИЭТ 82079-1 и ИСО/ИЭК/ИЭТ 26514).

• Начинайте каждый шаг с глагола в повелительном наклонении: «Откройте», «Запустите», «Проверьте».
• Одно действие на один шаг и одна инструкция на одно предложение. Держитесь примерно до 20 слов в предложении.
• Укажите, что пользователь должен увидеть после завершения шага.
• Размещайте предупреждения перед шагом, к которому они относятся, а не после него.
• Используйте одни и те же термины последовательно во всех местах. Если где-то используется слово «терминал», оно не должно называться иначе, например «консолью».
• Объясняйте термин при первом его использовании.

Слабый шаг:

Настройте веб-сайт и убедитесь, что всё работает.
Лучше шаг:

3. Проверьте конфигурацию

Выполните:

sudo nginx -t

Вы должны увидеть:

nginx: configuration file /etc/nginx/nginx.conf test is successful

Если вы видите что-то другое, перейдите к разделу «Устранение неполадок».

Команда, ожидаемый результат и плейсхолдеры

• Помещайте команды в блок кода, а ожидаемый результат — в отдельный блок ниже.
• Используйте форматирование кода для имён файлов, путей к файлам и команд в основном тексте, например /etc/nginx/.
• Никогда не указывайте настоящие пароли, ключи или внутренние адреса. Используйте явные плейсхолдеры: <server-ip>, <имя_пользователя>, <домен>.
• Держите строки кода примерно короче 70 символов, чтобы они не обрезались при печати на бумаге.

Отладка

Организуйте отладку вокруг того, что видит пользователь:

Симптом → возможные причины → обследование → решение → верификация

Метод описан в статье [[Feilsokingsmetode Level 1 - Systematisk feilsøking|Метод устранения неполадок]].

Скриншоты

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

• Windows: Клавиша Windows + Shift + S
• Mac: Cmd + Shift + 4

![Nginx Proxy Manager показывает прокси-хост со статусом Online](bilder/proxy-online.png)

Печать в PDF

1. Откройте руководство в предпросмотре в VS Code или откройте файл на GitHub.
2. Выберите печать. Windows: Ctrl + P. Mac: Cmd + P.
3. Выберите «Сохранить как PDF».
4. Просмотрите PDF-файл. Убедитесь, что ни одна строка кода, таблица или изображение не обрезаны.

Получите обратную связь до сдачи работы

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

1. Корректность: Есть ли шаги или утверждения, в которых вы сомневаетесь?
2. Аудитория и структура: Понятно ли, для кого предназначено руководство и что должно быть сделано в первую очередь?
3. Язык и действия: Содержит ли каждый шаг одно действие и ожидаемый результат? Объяснены ли термины?
4. Безопасность: Указано ли то, чего не следует публиковать?

Назовите две сильные стороны и два конкретных предложения по улучшению. Будьте вежливы и конкретики: фраза «Предлагаю объяснить proxy (прокси) на шаге 2, потому что …» полезнее, чем просто «непонятно». Больше о том, как давать обратную связь: NDLA Как дать обратную связь?.

Задача 1 — Улучшение слабых шагов

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

1. «Теперь нужно запустить контейнер и проверить, что он работает.»
2. «Измените конфигурацию, не забудьте протестировать её после этого и затем загрузить заново.»
3. «Войдите на сервер с паролем Sommer2026! и перейдите в папку с веб-сайтом.»

Задача 2 — Напишите краткое руководство

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

1. Укажите, для кого предназначено руководство и что они смогут делать после его изучения.
2. Опишите от трех до шести шагов с ожидаемым результатом.
3. Добавьте хотя бы один пункт в раздел устранения неполадок.
4. Попросите одноклассника следовать руководству без каких-либо объяснений с вашей стороны. Исправьте то место, где он остановился.

Дополнительные материалы для чтения

• NDLA: Создание инструкций по эксплуатации и информации для различных групп пользователей
• NDLA: Разработка учебных материалов
• Языковой совет: Ясность языка
• О четырёх типах документации на сайте Diátaxis (на английском языке)