Использование прототипа в качестве спецификации продукта API

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

Я узнал, что монолитный документ с требованиями к продукту (PRD) — далеко не идеальный способ сделать это, и что тестируемый интерфейс, включающий ту же информацию, что и спецификация продукта, был бы мощной альтернативой. Проблема с PRD в том, что они часто бывают очень большими и в основном текстовыми. Слишком легко потерять свое место или пропустить что-то действительно важное.

Наши друзья в UX решили эту проблему с помощью таких инструментов, как Invision , где они предоставляют интерактивный интерфейс, который вы можете потрогать и использовать, а не документ или каркас, который просто описывает интерфейс. Поскольку API — это интерфейс, нам нужен инструмент, который позволит взаимодействовать со спецификацией в режиме реального времени, а не с кучей описательного текста и JSON в документе.

Определение требований

Как должен выглядеть этот тестируемый интерфейс в качестве спецификации продукта? Как это будет работать? Он существует?

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

Требования Кагана*:

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

Список желаний Кагана*:

• Вам нужно будет дополнить прототип [с]:
  • Бизнес-логика
  • Требования к выпуску
  • Требования к доставке платформы
  • Случаи применения
• Я действительно хочу иметь возможность аннотировать прототип

Мои требования к прототипу как спецификации:

• Прототип должен быть спецификацией.
• Документация должна быть интегрирована в прототип.
• Все в компании, кому это нужно, должны иметь доступ к прототипу и документации.
• Заказчик должен иметь доступ к функциональной части прототипа для пользовательского тестирования.
• Прототип должен заменить спецификацию и работать максимально близко к предполагаемому функционалу, не накручивая готовый продукт.
• Должно быть легко вносить и фиксировать изменения в прототипе.
• Должно быть легко создавать варианты A/B, которые может протестировать любой, у кого есть доступ к прототипу.
• Должно быть легко экспортировать клиентскую документацию из прототипа.

Представляем стоп-свет

Инструмент, который я использовал и который удовлетворяет почти всем вышеперечисленным, называется Stoplight.io . По своей сути это механизм документации API и веб-прокси. Он позволяет вам определять свой API с помощью интуитивно понятного пользовательского интерфейса, в котором за кулисами используются лучшие возможности Swagger и RAML в качестве механизма спецификации, а также возможность импорта или экспорта из любого формата.

Поскольку StopLight — это инструмент документирования, вы можете определить запросы, ответы, заголовки и описания для своих конечных точек. С помощью функции прокси вы можете вызвать свой API и убедиться, что ваши вызовы соответствуют вашей спецификации, или автоматически обнаружить свои конечные точки, чтобы автоматически написать большую часть документации.

Прокси StopLight также имеет несколько других совершенно удивительных функций:

• Возможность совершать фиктивные вызовы на ваши конечные точки, если ваш продукт еще не готов или вы не хотите передавать свои запросы через прокси.
• Локальный сервер для тестирования вашего прототипа на вашей машине.
• Удаленный сервер для тестирования вашего прототипа в Интернете.
• Промежуточное ПО, написанное на Javascript, для определения кода, который может выполняться до и/или после вызова конечных точек вашего прототипа.

Если вы сравните комбинацию моего списка пожеланий, требований спецификации Кагана и его списка пожеланий с функциональностью, которую предоставляет StopLight, вы увидите, что StopLight удовлетворяет все потребности и желания:

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

Рабочий процесс в StopLight прост и может быть выполнен любым , независимо от его технических возможностей:

• Создайте новый проект.
• Добавьте спецификацию, щелкнув и введя информацию о конечной точке, ее параметрах, запросе и ответе.
• Добавьте в спецификацию информацию о вашем прототипе на экране «Определение».
• Если у вас есть дополнительные функции, добавьте их с помощью промежуточного программного обеспечения.
• Включите издевательство.
• Скопируйте/вставьте общедоступный URL-адрес фиктивного сервера и поделитесь им для обратной связи.

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

Как менеджер по продуктам для разработчиков, StopLight не только помогает мне более эффективно выполнять свою работу, он чрезвычайно прост в использовании и упрощает этапы подготовки к доставке для документирования API, поскольку документация была начата до этапов проверки клиентов и обновляется. на протяжении всего процесса. Есть много других вариантов использования и функций, которые предоставляет StopLight, но это, возможно, наиболее существенно повлияло на мою работу.

*Требования и список пожеланий Кагана являются прямыми цитатами из Inspired: How to Build Products Love Customers.