Привет, Хабр! Я Аля — старший продакт-менеджер выделенных серверов Selectel. Когда-то давно я думала: «Что такого сложного во внутренней документации? Почему столько проблем с тем, чтобы она была актуальной, полезной и легко поддерживаемой? Делов-то». Оказалось, не все так просто.

При работе с нашей документацией я столкнулась с целым «букетом» сложностей.

• Как при запуске нового продукта или сервиса определить структуру так, чтобы начать с чего-то простого, а дальше можно было масштабировать?
• Как сделать структуру понятной не только тебе, но и другим членам команды? Иногда то, что понятно для тебя, для других максимально нелогично.
• Как сделать документацию полезной не только для разработки, но и для продаж, маркетинга, саппорта и других команд?
• Как держать документ в актуальном состоянии, при этом не посвящать этому все время?

В статье я расскажу, как справиться с этими сложностями. Я сфокусируюсь на легковесной структуре документации, дополню рассказ комментариями вида «а еще пробовала вот это, но не сработало», а также приправлю рекомендациями по масштабированию.

Используйте навигацию, если не хотите читать текст целиком:

→ Легковесная базовая документация
→ Как может выглядеть структура документации
→ Рекомендации: как работать с документацией, когда продукт и команда растут
→ Заключение

Легковесная базовая документация

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

Сейчас я уверена, что продукт можно запустить и без документации. Так что перед началом сравните все плюсы и минусы. Задумайтесь, дает ли она преимущества или тормозит вас.

Какие преимущества открывает документация?

• Упрощается коммуникация внутри команды. Не все продукты создают два-три человека — иногда людей гораздо больше. А документация в этом случае выравнивает команду в том, в каком направлении и зачем она движется.
• Снижается риск утраты знаний — ключевые сотрудники бывают недоступны: уходят в отпуск, берут больничный или вовсе покидают команду. Если есть знания, которые важно сохранить, документация в этом поможет.
• Можно проверить идею — точно ли она так хороша, как вы думаете?
• Появляются инструменты для продаж, маркетинга и поддержки, которые позволят их значительно улучшить. Например, описание преимуществ продукта будет полезно для продаж и маркетинга, а основные вопросы и ответы по работе продукта — технической поддержке.
• Ускоряются будущие изменения — при дальнейшей доработке продукта команда может опираться на ранее зафиксированные решения.

Сейчас в открытом доступе можно найти сотни или даже тысячи шаблонов для документации (а с GenAI их можно нагенеририровать бесконечное множество). Несмотря на такое многообразие, многие шаблоны тяжеловесны настолько, что пока прочитаешь названия разделов — устанешь. Это приводит к чрезмерному фокусу на документации вместо запуска и развития продукта, а еще — более сложному наполнению и поддержанию в будущем.

Во всеобъемлющих сборниках накопленной мудрости нет ничего плохого, но на старте это может помешать и сделать хуже. Если уж и писать внутреннюю документацию, то начинать с чего-то простого, но при этом полезного. Например, с Press Release (PR) и Frequently Asked Questions (FAQ) от Amazon. Это ключевой документ, который используется для обеспечения общего понимания идеи всеми заинтересованными сторонами. PR/FAQ — отправная точка для всех последующих документов о продукте и макетов.

Другой пример простой документации — различные канвасы, например, — Lean Canvas и The Value Proposition Canvas. Они помогают сосредоточиться на проблемах, решениях, ключевых метриках и конкурентных преимуществах, что особенно важно как на старте, так и дальнейшем развитии продукта.

Вполне возможно, вам хватит этих артефактов на старте, а основная документация у вас будет вида «в коде посмотри».

Как может выглядеть структура документации

Если вам требуется более подробная внутренняя документация, предлагаю обратить внимание на базовую структуру, которая легко ложится в Confluence-подобные системы.

Эта структура — результат 7+ лет моей работы и множества итераций.

О продукте — рассказываем кратко и емко: что это, для кого и зачем. Прочитав эту страницу, человек должен сразу понять, для чего и кого существует ваш продукт.

Customer & Value — клиентские сегменты и кейсы и контексты использования продукта:

• В чем ценность для пользователей, чем продукт лучше альтернатив?
• Какие сегменты целевой аудитории / пользователей — кто они, чем отличаются друг от друга. Какие могут быть контексты, кейсы, задачи, проблемы и боли?

Мне бы хотелось сказать: «Здесь используйте Jobs to be Done (JTBD) или User personas», но универсального фреймворка не существует. Выбирайте любой готовый или придумайте что-то свое.

• Какие есть ключевые преимущества для разных сегментов и кейсов.
• Сравнение с конкурентными решениями — чем мы лучше?

Классный (но не единственный) формат — battle cards. Мне нравится тем, что он понятный и простой в использовании, а подход с «битвой» позволяет сделать процесс с подготовкой веселым и захватывающим.

Запуск и продвижение:

• Какая стратегия выхода на рынок или go-to-market (GTM) strategy — план действий при запуске нового продукта. Он должен включать четкое описание целей запуска, позиционирование продукта на рынке, каналы и способы распространения, борьбу с конкурентами и другие аспекты, которые важны для успешного запуска.
• Описание планов и дальнейшее развитие.

FAQ & How-to — ответы на все вопросы.

Почему я объединила вопросы и ответы с инструкциями — по моему опыту они почти всегда идут рука об руку. Если человек ищет ответ на вопрос, как что-то создать, скорей всего, ему нужно это создать. А значит, ему нужна инструкция. Например, вопрос «Как мне заказать сервер клиенту через админскую панель управления?» сразу же хочется сопроводить инструкцией (how-to) — как это сделать.

FAQ может быть полезным поделить по направлениям — скорей всего техническая поддержка и продажи будут приходить с очень разными вопросами.

Решение:

• Техническая архитектура продукта — структура системы, способы взаимодействия ее компонентов и технические решения, используемые для реализации продукта. Этот раздел помогает всем участникам команды разработки понимать, как устроен продукт на уровне технологий и инфраструктуры.
• Функциональность продукта — что доступно для пользователей, как это работает, какие есть особенности и ограничения.

Product Discovery:

• Раздел, в котором собираются все ваши исследования — исследования пользователей (интервью, опросы и анкеты, полевые исследования и другие исследования вокруг ваших пользователей), юзабилити-тестирования, продуктовая аналитика и другие исследования.

Опциональные разделы, которые зависят от особенностей вашего продукта, но могут быть важны уже на этапе запуска:

• поддержка продаж — особенно актуально для В2В. В этом разделе могут лежать полезные материалы для продаж;
• руководства для пользователей;
• скидки и спецпредложения;
• обновления в продукте или релиз-ноутсы;
• команды и процессы — описание команд продукта, зон ответственности, процессов и процедур;
• онбординг в продукт;
• meeting notes. Почему этого раздела нет в основной структуре — обсуждения обычно бывают в каком-то контексте, поэтому заметки лежат в разделе контекста. Например, если вы обсуждаете конкретное юзабилити-тестирование, то заметки по нему логичнее положить в раздел этого исследования, а не какой-то отдельный.

Рекомендации: как работать с документацией, когда продукт и команда растут

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

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

Централизируйте «хранение». Возможно, в этот момент вы удивитесь, сейчас все говорят про децентрализацию, а тут наоборот.

Децентрализация — это нормально. Скорее всего, у вас будет много разных источников. Я же говорю про единый инструмент, в котором хранится основная документация и ссылки на документацию, хранящуюся в других местах. Например, для документации исследований мы используем Confluence, но для расчетов применяем таблицы в онлайн-офисе, а для прототипов — Figma или Pruffme-доски. И так еще целый ряд инструментов под разные задачи. В Confluence в этом случае мы даем ссылки на другие источники.

Вовлекайте команду в формирование и поддержание документации в актуальном состоянии. Конечно, можно выделить ответственную роль за обновление всей документации — техписа. Но когда у вас большая команда и изменений в продукте много, такой подход плохо масштабируется.

Вовлечение команды в написание и актуализацию документации — решение, которое лучше масштабируется. Только работает оно хорошо, когда часть с документацией встроена в цикл разработки, а также есть стандарты и шаблоны (об этом ниже). Как альтернатива или промежуточное решение — назначение владельцев разделов.

Используйте шаблоны. Большинство инструментов для документации позволяет формировать шаблоны — они значительно ускоряют работу над документом и помогают упростить его восприятие. Примеры, когда будут особенно полезны шаблоны: FAQ, meeting notes, страница исследования, документация интервью и т.д.

Встраивайте документацию в процесс разработки в процесс разработки. Значительно проще помнить про ведение документации, когда это встроено в процесс работы над задачей. Например, у нас написание и обновление документа — часть работы над задачей, еще точнее — acceptance criteria.

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

Переиспользуйте документацию или сформируйте «строительные блоки». Возможно, одна и та же информация встречается в разных разделах. Например, про целевую аудиторию и преимущества продукта важно знать маркетингу и продажам. Если такое происходит, напишите информацию в одном месте, а в других переиспользуйте. Например, в Confluence это можно сделать через макросы «A Shared Blocks» + «Include A Shared Blocks» (подробнее про использование макросов рассказывали в статье). Очень удобно: если вы измените информацию в одном разделе, в другом она автоматически обновится.

Автоматизируйте формирование и обновление документации. Можете формировать release notes, беря resolution comment из Jira-задач — обязательно воспользуйтесь этим.

Используйте AI writing assistants. Они помогут со структурой, написанием и редактирование — это сэкономит ваше время.

Наблюдение.У нас в команде не очень работают лонгриды, даже с хорошей структурой и форматированием. Из-за этого мы стараемся создавать отдельные, по возможности легковесные страницы. Например, когда мы делаем страницу фичи, то на родительской странице размещаем только основную информацию, а технические детали по разработке описываем на дочерней странице.

Заключение

Документация продукта может стать полезным инструментом, если создать ее простой, понятной и актуальной. Надеюсь, что мои рекомендации помогут вам сделать этот документ помощником, а не источником дополнительного стресса.

Помните, что над документацией работают люди (много разных людей), поэтому она никогда не будет идеальной. Могут встречаться дублирования, неактуальные страницы и другие недочеты. И это нормально, главное, чтобы документация оставалась полезным инструментом.