Справка нужна тогда, когда поддержка третий месяц отвечает на одни и те же вопросы, а новый пользователь бросает продукт на втором экране. Я начинаю именно с этого: смотрю, о чём спрашивают чаще всего, где ломается первый сценарий, какими словами люди называют ваши функции. Эта картина и превращается в оглавление — сначала первый запуск и первый понятный результат, потом повседневные операции, и только в конце редкие и сложные случаи, до которых новичок всё равно не дойдёт.
Дальше пишу: пошагово, со скриншотами, без «интуитивно понятно» и «просто нажмите». Ошибки вынесены в отдельный раздел — видимый текст, причина, что сделать. Для разработчиков отдельно идёт описание API: методы, поля, коды ответа, готовые примеры запроса и ответа, которые можно скопировать и выполнить. Термины сведены в словарь, стиль и тон зафиксированы памяткой, чтобы следующая статья не выбивалась из ряда. Исходники отдаю в формате, который вы сможете править своими силами, без привязки к моему рабочему инструменту.
Оговорки, которые действуют всегда: каждая инструкция проверяется прохождением по шагам на живом продукте, и то, что держится только «на памяти разработчика», в справку не идёт. Ключи, токены и тестовые доступы в примерах стоят заглушками. Раздел о функции, которая ещё не доделана, помечается черновиком, а не выдаётся за готовую документацию.
— сбор частых вопросов и разбор продукта по сценариям
— оглавление от первого запуска к сложным задачам
— инструкции по шагам со скриншотами и подписями
— раздел частых ошибок: текст, причина, что делать
— описание API с примерами запросов и ответов
— словарь терминов, единый стиль и тон изложения
— прогон готовых инструкций на живом продукте
— передача исходников в удобном для правок формате
Дальше пишу: пошагово, со скриншотами, без «интуитивно понятно» и «просто нажмите». Ошибки вынесены в отдельный раздел — видимый текст, причина, что сделать. Для разработчиков отдельно идёт описание API: методы, поля, коды ответа, готовые примеры запроса и ответа, которые можно скопировать и выполнить. Термины сведены в словарь, стиль и тон зафиксированы памяткой, чтобы следующая статья не выбивалась из ряда. Исходники отдаю в формате, который вы сможете править своими силами, без привязки к моему рабочему инструменту.
Оговорки, которые действуют всегда: каждая инструкция проверяется прохождением по шагам на живом продукте, и то, что держится только «на памяти разработчика», в справку не идёт. Ключи, токены и тестовые доступы в примерах стоят заглушками. Раздел о функции, которая ещё не доделана, помечается черновиком, а не выдаётся за готовую документацию.
— сбор частых вопросов и разбор продукта по сценариям
— оглавление от первого запуска к сложным задачам
— инструкции по шагам со скриншотами и подписями
— раздел частых ошибок: текст, причина, что делать
— описание API с примерами запросов и ответов
— словарь терминов, единый стиль и тон изложения
— прогон готовых инструкций на живом продукте
— передача исходников в удобном для правок формате
