Как оформить документацию продукта

Хорошая документация отвечает на вопросы до того, как их зададут. Она помогает пользователям освоить продукт и снимает часть нагрузки с поддержки. Оформление здесь не менее важно, чем содержание.

Зачем документация

Пользователь, который не понял продукт, уходит. Документация объясняет, как всё устроено, и снижает число обращений. Она также экономит время команды: вместо повторных объяснений вы даёте ссылку на инструкцию.

Структура

Разделите документацию по этапам работы с продуктом:

• Начало: что это и как зарегистрироваться.
• Основные действия: как выполнить частые задачи.
• Настройки: тонкая настройка под себя.
• Частые проблемы и решения.
• Справочник: описания полей и терминов.

Каждый раздел отвечает на свой круг вопросов. Не смешивайте туториал и справочник в одной статье.

Оглавление и навигация

• Оглавление в начале длинной страницы.
• Навигация между соседними статьями внизу.
• Ссылки на связанные разделы прямо в тексте.
• Хлебные крошки, чтобы понимать, где вы находитесь.

Для длинных инструкций удобно, когда рядом есть время чтения: пользователь понимает, сколько займёт материал. А оглавление собирается автоматически из заголовков.

Читаемость

Пишите короткими абзацами и по шагам. Один шаг это одно действие. Если действие сложное, разбейте его на два. Примеры кода оформляйте отдельным блоком, а названия кнопок выделяйте так, чтобы их было видно.

Держите один стиль по всему тексту: одинаковые термины, одинаковые названия кнопок. Это мелочь, но именно она путает пользователей.

Как поддерживать

Документация устаревает быстрее, чем кажется. Обновляйте её вместе с продуктом, а не после. Храните материалы рядом с продуктом, чтобы изменения не терялись. Периодически проходите раздел за разделом и проверяйте, что шаги работают.

Итог

Документация помогает пользователям и разгружает поддержку. Постройте понятную структуру, добавьте оглавление и навигацию и следите за актуальностью. Про родственный формат читайте в статье "Как сделать базу знаний".