Спробував зібрати дев’ять причин, через які варто документувати програмні продукти. Частину користі видно одразу, коли клієнт читає інструкцію. Решту помічаєш згодом, коли треба пригадати, чому система працює саме так.
Документація як частина роботи команди
- Окрема оплачувана робота. Із замовником можна погодити обсяг документації, її формат і порядок приймання. Наприклад, окремо оцінити посібник адміністратора, навчальні сценарії та подальше оновлення матеріалів.
- Нагода переосмислити систему. Поки пояснюєш алгоритм, мимоволі перевіряєш, чи можна його зрозуміти без підказок автора. Часто саме тоді знаходиш зайвий крок або правило, якого бракує в інтерфейсі.
- Пам’ять команди. Після перерви легше відновити логіку рішення, якщо поруч із кодом записано, чому обрали цей варіант і які обмеження врахували.
- Перевірка якості. Коли для процедури є опис із прикладом і очікуваним результатом, іншому учаснику команди простіше її відтворити та помітити розбіжність.
Що отримує клієнт і майбутній користувач
- Зрозуміла інформація про продукт. Стаття 15 Закону України № 1023-XII описує право споживача на інформацію про продукцію. У роз’ясненні Держмитслужби супровідна документація наведена серед можливих способів її надання. Склад і формат матеріалів для конкретного програмного продукту визначають за застосовними нормами та умовами договору.
- Менше повторних пояснень. Якщо кілька клієнтів питають, як виконати одну операцію, варто описати її один раз і надалі давати посилання на потрібний розділ.
- Простіше навчання. Короткі інструкції за ролями допомагають новачку почати зі свого завдання. Для оператора складу це може бути приймання товару, для адміністратора — налаштування доступу.
- Знайомство з продуктом через пошук. Відкрита документація дає змогу знайти рішення за конкретним запитом. Відвідувач може спочатку прочитати, як працює потрібний процес, і вже тоді звернутися із запитанням.
- Підстава для вибору. З опису видно призначення продукту, його можливості й межі. Інколи саме один добре пояснений сценарій допомагає клієнтові вирішити, чи підходить йому система.
З чого почати
Я б узяв дію, про яку найчастіше питають у підтримки. Записав би, які права й дані потрібні перед початком, що натиснути та як перевірити результат. Потім дав би інструкцію колезі, який цю дію ще не виконував. Його запитання підкажуть, чого бракує в тексті або в самому продукті.
