Технічна документація та довідка продукту

Пишу технічну документацію та довідку продукту — посібник користувача, базу знань, опис API. Починаю не з переліку розділів, а з розбору самого продукту: проходжу його як новачок, занотовую місця, де застряг, і збираю справжні задачі, з якими приходять користувачі. Саме з цих задач і виростає структура довідки — від першого запуску та першої вдалої дії до щоденної роботи, а вже потім до складних сценаріїв, потрібних небагатьом, але таких, що з'їдають найбільше часу підтримки.

Кожна стаття — це кроки зі знімками екрана, підписаними так, щоб читач не вгадував, куди натискати. Окремим розділом ідуть часті помилки й що робити: текст помилки, причина, вихід. В описі API біля кожного методу стоять приклади запиту та відповіді, розібрані поля й коди стану, сказано, що повертається у разі відмови. Словник термінів тримає назви в одному місці, щоб інтерфейс, довідка та відповіді підтримки говорили однаковими словами, а єдиний стиль і тон закріплені короткою пам'яткою — тоді текст лишається цілісним навіть тоді, коли його згодом дописують інші.

Кожна інструкція перевіряється проходженням по кроках на живому продукті; написане «з пам'яті розробника», без такої перевірки, до довідки не потрапляє. Ключі, токени й тестові доступи у прикладах замінюються на заглушки. Документація до незавершеної функції позначається чернеткою, а не видається за готову.

— розбір продукту та перелік справжніх задач користувача
— структура довідки від першого запуску до складних сценаріїв
— покрокові інструкції зі знімками екрана та підписами
— розділ «часті помилки і що робити»
— опис API з прикладами запитів і відповідей
— словник термінів і пам'ятка щодо стилю та тону
— перевірка кожної інструкції на живому продукті
— передача початкових файлів у зручному для правок форматі