Це машинний переклад тексту, який може містити помилки!
Коротко у зведенні
- Інструкція для користувача допомагає конкретній особі виконати одну конкретну задачу.
- Кожен крок містить одну дію та вказує, що має побачити користувач після цього.
- Інструкцію вважають завершеною лише тоді, коли хтось, хто не знайомий із системою, пройшов її від початку до кінця.
Хто має використовувати її?
Завжди спочатку запитуйте: Хто буде користуватися посібником і що він повинен вміти після його завершення?
Новий працівник ІТ-відділу, який знає роботу з терміналом, потребуватиме іншого посібника, ніж учитель, який ніколи не відкривав його. Тому одна й та сама система може потребувати кількох посібників. Визначте, що отримувач уже вміє, до чого у нього є доступ і які слова йому незрозумілі.
Який це тип документа?
Керівництво користувача є інструкцією з дій: воно допомагає користувачеві виконати одну задачу. Це не підручник, довідник чи пояснення того, чому система працює так, як вона працює.
| Тип документа | Питання читача | Приклад |
|---|---|---|
| Інструкція з дій | Як мені це зробити? | Так ви публікуєте нову версію застосунка |
| Навчання | Як я вивчу це? | Ваш перший контейнер, крок за кроком |
| Довідник | Яке значення або команда? | Список портів і служб |
| Пояснення | Чому це працює так? | Чому ми використовуємо reverse-proxy |
Якщо користувачу потрібне пояснення по ходу справи, тримайте його коротким і розміщуйте там, де йому потрібно.
Части в інструкції
| Частина | На що вона відповідає |
|---|---|
| Мета | Що досягнув користувач після виконання інструкції? |
| Перед початком | Які доступи, програми, файли та попередні знання потрібні? |
| Кроки по кроках | Що робить користувач у якій послідовності і на що має звернути увагу після кожного кроку? |
| Приклади | Як виглядають команда, налаштування або правильний результат? |
| Виявлення помилок | Що робить користувач, якщо результат не відповідає очікуванням? |
| Якщо потрібно скасувати дії | Як відновити зміну, яка виявилася помилковою? |
| Перевірочний список | Як користувач перевіряє, чи все правильно наприкінці? |
| Важливі поради | Що ви навчилися, про що повинен знати користувач? |
| Джерела та контроль | На яких джерелах, якому версії та якому тестовому середовищі ґрунтується інструкція? |
Як написати крок
Правила базуються на стандартах для інструкцій та документації користувача (IEC/IEEE 82079-1 та ISO/IEC/IEEE 26514).
- Починайте кожен крок з дієслова в наказовому способі: «Відкрийте», «Запустіть», «Перевірте».
- Виконуйте одну дію за кроком і давайте одну інструкцію на речення. Тримайте речення обсягом менше приблизно 20 слів.
- Описуйте те, що бачитиме користувач після завершення кроку.
- Розміщуйте попередження перед тим кроком, до якого вони стосуються, а не після нього.
- Використовуйте ті самі слова для позначення одного й того ж поняття протягом усього документа. Якщо десь воно називається «терміналом», то нигде більше його не слід називати «консоллю».
- Поясніть термін при першому використанні.
Слабкий крок:
Налаштуйте веб-сайт і перевірте, що все працює.
Кращий крок:3. Перевірте конфігурацію
Виконайте:
sudo nginx -tВи маєте побачити:
nginx: configuration file /etc/nginx/nginx.conf test is successfulЯкщо ви бачите щось інше, перейдіть до розділу «Пошук помилок».
Команда, очікуваний результат та заповнювачі
- Розміщуйте команди в блоці коду, а очікувані результати — у окремому блок нижче.
- Використовуйте формат коду для імен файлів, шляхів до файлів та команд у звичайному тексті, наприклад
/etc/nginx/. - Ніколи не пишіть реальні паролі, ключі або внутрішні адреси. Використовуйте чіткі заповнювачі:
<server-ip>,<ім'я_користувача>,<домен>. - Дотримуйтесь обмеження довжини рядків коду приблизно 70 символами, щоб вони не обривалися при друкуванні.
Відладка
Будуйте процес відлагування навколо того, що бачить користувач:
Симптом → можливі причини → дослідження → рішення → верифікація
| Симптом | Можлива причина | Дослідження | Рішення | Як ви побачите, що проблема вирішена |
|---|---|---|---|---|
| Вебсайт відображає «502 Bad Gateway» | Сервіс у тилу не відповідає | Виконайте docker compose ps і перевірте, чи запущено контейнер | Запустіть контейнер за допомогою docker compose up -d | Сторінка завантажується, а в стовпці STATUS команда docker compose ps показує «Up» |
Метод описаний тут: [[Feilsokingsmetode Level 1 - Systematisk feilsøking|Метод діагностики]].
Скріншоти
Використовуйте скріншот лише тоді, коли він допомагає користувачу впізнати правильний результат. Обріжте зображення, позначте найважливіше стрілкою або номером та видалите конфіденційну інформацію. Напишіть альтернативний текст, який пояснює, що показано на зображенні.
- Windows: Клавіша Windows + Shift + S
- Mac: Cmd + Shift + 4
Друк у форматі PDF
- Відкрийте посібник у режимі попереднього перегляду в VS Code або відкрийте файл на GitHub.
- Оберіть друк. Windows: Ctrl + P. Mac: Cmd + P.
- Оберіть «Зберегти як PDF».
- Перегляньте PDF-файл. Перевірте, щоб жоден рядок коду, таблиця чи зображення не були обрізані.
Отримайте зворотний зв’язок перед наданням
Попросіть одногрупника прочитати інструкцію, перш ніж заявляти, що вона завершена. Той, хто надає зворотний зв’язок, відповідає коротко та посилається на конкретне місце в тексті:
- Точність: Чи є кроки або твердження, у яких ви сумніваєтесь?
- Аудиторія та структура: Чітко визначено, для кого призначена інструкція і які елементи мають бути готовими насамперед?
- Мова та дії: Чи містить кожен крок одну дію та очікуваний результат? Пояснено термінологію?
- Безпека: Наведено щось, чого не слід було оприлюднювати?
Назвіть дві сильні сторони та два конкретних способи покращення. Будьте доброзичливими та конкретними: «Я пропоную пояснити проксі на 2-му кроці, тому що …» корисніше, ніж просто «нечітко». Більше про те, як надавати зворотний зв’язок: NDLA Як давати відгуки?.
Завдання 1 — Покращте слабкі кроки
Переформулюйте кожен так, щоб він містив один дієслово в наказовому способі, одну дію та очікуваний результат. Розбийте кроки, що містять кілька дій.
- «Тепер контейнер має бути запущений і необхідно перевірити, чи він працює».
- «Змінити конфігурацію, не забути протестувати її після цього і перезавантажити».
- «Увійдіть на сервер із паролем Sommer2026! і перейдіть до папки з вебсайтом».
Завдання 2 – Напишіть коротку інструкцію
Оберіть завдання, яке ви можете виконати без допомоги, наприклад запуск контейнера або публікація змін на вебсайті.
- Наведіть інформацію про те, для кого призначена інструкція та що вони повинні вміти робити після її використання.
- Опишіть від трьох до шести кроків із очікуваним результатом.
- Додайте щонайменше один рядок у розділ усунення несправностей.
- Попросіть однокласника виконувати дії відповідно до інструкції, а сам нічого не пояснюйте. Виправте помилки там, де він зупинився.
Більше для читання
- NDLA: Створення інструкцій та інформації для різних груп користувачів
- NDLA: Розробка навчальних матеріалів
- Радник з мови: Ясна мова
- Diátaxis про чотири типи документації (англійською)