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