Продуктовые и программные команды разделяют общую проблему: документацию¶
Продуктовая документация — это руководства и инструкции для пользователей, объясняющие рабочие процессы и интерфейс продукта. Как обычному пользователю эффективно работать с продуктом? В этом смысле продуктовая документация применима к программным продуктам.
Программная документация описывает базовые технологии, требования и настраиваемые атрибуты программного продукта. Как ИТ-администраторам настраивать, отслеживать, размещать и развертывать программный продукт для пользователей? Этот тип документации особенно важен при наличии нескольких версий или веток продукта.
По сути, продуктовая документация похожа на обучение вождению автомобиля. Руль поворачивает машину, педаль газа разгоняет, педаль тормоза останавливает. Программная документация объясняет, как устроен автомобиль. Руль соединен с передней осью, которая поворачивает передние колеса для изменения направления движения; педаль газа увеличивает поток воздуха в двигатель, что привлекает больше топлива, генерируя крутящий момент и мощность.
Оба типа документации важны. Один обучает пользователей, другой — администраторов и разработчиков. Здорово показать людям, как водить машину, но что произойдет, когда машина сломается, если никто не знает, как она работает?
Небольшие различия между продуктовой и программной документацией¶
Между продуктовой и программной документацией есть несколько важных отличий:
Целевая аудитория и персоны¶
Продуктовая документация ориентирована на единственную аудиторию — пользователя. Она предполагает, что пользователь не имеет технических знаний, и написана простым языком с минимумом жаргона. Как техническое ученичество в сравнении с университетским образованием, она учит людей выполнять задачи, меньше концентрируясь на теоретических или концептуальных знаниях.
Программная документация нацелена на ИТ-администраторов, инженеров и разработчиков. Она охватывает дизайн и архитектуру программного обеспечения, инструкции по настройке через командную строку, поддержку API и интеграций, управление данными и отчетность, сетевую топологию — все шестеренки, заставляющие машину работать. Эти документы формируют единый источник правды (SSOT), к которому ИТ-персонал может обращаться при мониторинге и устранении неполадок.
Частота обновлений¶
Программная документация должна постоянно обновляться по мере слияния новых коммитов с основным каналом релизов. Она должна описывать новые функции и команды, а также отмечать устаревшие возможности. Необходимо документировать новые или изменяющиеся зависимости и уточнять поддержку функций на всех целевых платформах — например, работает ли функция в Windows, но не в Linux.
Продуктовая документация требует обновления только когда изменения в программном коде вызывают изменения в рабочих процессах или удобстве использования. Если разработчик меняет код платежного шлюза, но процесс оплаты для пользователей остается прежним, обновления не требуются.
Это показывает естественную иерархию документации программного продукта. Техническая программная документация формирует фундамент, а продуктовая документация строится на этом фундаменте. Поэтому стоит сосредоточиться на создании качественной программной документации, которая порождает еще более качественную продуктовую документацию.
Примеры структуры продуктовой и программной документации¶
Продуктовая документация может следовать такой структуре:
- Название продукта
- Обзор назначения продукта
- Руководство по настройке
- Объяснение функции 1 с изображениями
- Объяснение функции 2 с изображениями
- Ссылки на службу поддержки
Аналогично программная документация может следовать такой структуре:
- Название программного обеспечения
- Обзор назначения программного обеспечения
- Зависимости программного обеспечения
- Руководство по установке
- Объяснение функции 1 с изображениями
- Объяснение функции 2 с изображениями
- Ссылки на техническую поддержку
Очевидно, что эти два типа документации тесно связаны между собой и следуют похожей структуре. Это означает, что продуктовые и программные команды могут многому научиться друг у друга и имеют большой потенциал при совместной работе над документацией.
Продуктовые и программные команды могут дополнять друг друга¶
Между продуктовой и программной документацией есть явные сходства. Возникает вопрос: могут ли продуктовые и программные команды работать вместе?
Да, могут, и должны!
Программные команды понимают технический жаргон и базовые технологии. Продуктовые команды понимают, что видят, хотят и в чем нуждаются пользователи — пользовательский опыт. Авторы программной документации могут предоставить подробную техническую информацию, а авторы продуктовой документации могут упростить технические детали для восприятия обычными пользователями.
Представьте, что пытаетесь объяснить что-то простым языком, не имея глубокого понимания, необходимого для формулировки понятной непрофессионалу. Именно это происходит, когда продуктовая документация создается до программной.
Что такое квантовая механика? Вероятно, первое, что приходит в голову — кот Шрёдингера! Но какое отношение квантовая механика имеет к котам? Для пользователя это не важно. Для физика это означает всё.
Начните с программной документации, завершите лучшей продуктовой документацией в Docsie¶
В заключение, использование программной документации как шаблона для последующей продуктовой документации даёт множество преимуществ. Программная документация должна служить единым источником правды для ИТ-персонала и авторов продуктовой документации. После её создания авторы продуктовой документации получают ясность и понимание для упрощения и обмена удобной информацией с клиентами, имея техническое руководство для проверки и обеспечения качества.
Проще говоря, начав с отличной программной документации, ваши авторы смогут создать еще лучшую продуктовую документацию!
Начните создавать документацию, которая помогает вашим клиентам делать больше. Зарегистрируйтесь в нашем тарифе Startup (навсегда бесплатно!) и дарите удовольствие от документации с Docsie!