Uso de un prototipo como especificación de producto API

Como gerente de productos de experiencia de desarrollador en SendGrid, tengo la tarea de identificar oportunidades, características y productos que involucran nuestra API. Una cosa en la que he estado trabajando es en la identificación de métodos para hacer que la comunicación de mis ideas de productos a otros PM, ingenieros y clientes sea más efectiva.

He aprendido que un Documento de requisitos del producto (PRD) monolítico es una forma menos que ideal de hacer esto y que una interfaz comprobable que incluya la misma información que una especificación del producto sería una alternativa poderosa. El problema con los PRD es que suelen ser muy grandes y en su mayoría de texto. Es muy fácil perder tu lugar o perderte algo realmente importante.

Nuestros amigos en UX han resuelto este problema con herramientas como Invision , donde brindan una interfaz en la que se puede hacer clic y que puede tocar y usar, en lugar de un documento o una estructura alámbrica que simplemente describe la interfaz. Dado que una API es una interfaz, necesitamos una herramienta que permita la interacción con la especificación en tiempo real, en lugar de un montón de texto descriptivo y JSON en un documento.

Definición de requisitos

¿Cómo debería ser esta interfaz comprobable como especificación de producto? ¿Cómo funcionaría? ¿Existe?

Mientras leía el Capítulo 18, "Reinventar la especificación del producto", de Marty Cagan's Inspired: How to Build Products Customers Love , me di cuenta de que quería compartir una herramienta que he estado usando y que satisface los requisitos de Cagan para una especificación de producto, la mayoría de su lista de deseos para las especificaciones del producto y mi propia lista personal de requisitos del prototipo como especificación.

Requisitos de Cagan*:

• La especificación debe describir la experiencia completa del usuario.
• La especificación debe representar con precisión el comportamiento del software.
• Debe poder comunicar el producto de manera que todas las partes interesadas obtengan lo que necesitan.
• La especificación cambiará
• Debe haber una única representación maestra de la especificación para reducir la ambigüedad y la versionitis.

Lista de deseos de Cagan*:

• Deberá complementar el prototipo [con]:
  • Lógica de negocios
  • Requisitos de liberación
  • Requisitos de entrega de la plataforma
  • casos de uso
• Tengo muchas ganas de poder anotar el prototipo.

Mis requisitos para el prototipo como especificación:

• El prototipo debe ser la especificación.
• La documentación debe estar integrada en el prototipo.
• Todas las personas de la empresa que lo necesiten deben tener acceso al prototipo y la documentación.
• El cliente debe poder acceder a la parte funcional del prototipo para las pruebas de usuario.
• El prototipo debe reemplazar la especificación y funcionar lo más cerca posible de la funcionalidad prevista sin conectar un producto terminado.
• Debe ser fácil realizar y registrar cambios en el prototipo.
• Debería ser fácil hacer variaciones A/B que puedan ser probadas por cualquier persona con acceso al prototipo.
• Debería ser fácil exportar la documentación del cliente desde el prototipo.

Presentamos StopLight

La herramienta que he estado usando y que satisface casi todo lo anterior se llama Stoplight.io . Es, en esencia, un motor de documentación API y un proxy web. Le permite definir su API utilizando una interfaz de usuario intuitiva, que tiene lo mejor de Swagger y RAML detrás de escena como su motor de especificación junto con la capacidad de importar o exportar desde cualquier formato.

Dado que StopLight es una herramienta de documentación, puede definir las solicitudes, las respuestas, los encabezados y las descripciones de sus terminales. Con la función de proxy, puede llamar a su API y verificar que sus llamadas coincidan con su especificación o descubrir automáticamente sus puntos finales para obtener la mayor parte de su documentación escrita automáticamente.

El proxy de StopLight también tiene otras características absolutamente sorprendentes:

• La capacidad de realizar llamadas simuladas a sus terminales si su producto no está terminado o si no desea enviar sus solicitudes por proxy.
• Servidor local para probar su prototipo en su máquina.
• Servidor remoto para probar su prototipo en Internet.
• Middleware, escrito en Javascript, para definir código que puede ejecutarse antes y/o después de llamar a los puntos finales de su prototipo.

Si compara la combinación de mi lista de deseos, los requisitos de especificación de Cagan y su lista de deseos con la funcionalidad que proporciona StopLight, puede ver que StopLight satisface todas las necesidades y deseos:

• Documentación solo interna del prototipo y sus características.
• Un prototipo completo de fácil acceso de la funcionalidad.
• Una interfaz comprobable que tiene la capacidad de alternar funciones variables para pruebas y comentarios de los usuarios.
• Una manera fácil de crear una versión de su prototipo para una conversación específica, de modo que pueda modificar la funcionalidad del prototipo casi en tiempo real para ilustrar y verificar los comentarios que ha recibido.

El flujo de trabajo en StopLight es simple y puede ser realizado por cualquier persona , independientemente de su habilidad técnica:

• Crear un nuevo proyecto.
• Agregue la especificación haciendo clic y escribiendo información sobre el punto final, sus parámetros, solicitud y respuesta.
• Agregue la información de especificación sobre su prototipo en la pantalla Definición.
• Si tiene características opcionales, agréguelas usando el middleware.
• Activa la burla.
• Copie y pegue la URL pública del servidor simulado y compártala para recibir comentarios.

Si va a visitar a un cliente y le gustaría experimentar con el prototipo en tiempo real, simplemente descargue la definición a su computadora, cree un nuevo proyecto con el nombre de su visita e importe la definición. Ahora puedes cambiar lo que quieras sin cambiar tu prototipo original. Cuando regresa y fusiona ideas, es tan fácil hacer cambios como lo fue construir el prototipo en primer lugar.

Como gerente de productos de experiencia de desarrollador, StopLight no solo me ayuda a hacer mi trabajo de manera más eficiente, sino que es muy fácil de usar y facilita los pasos de preparación de la entrega para documentar la API, ya que la documentación se inició antes de los pasos de validación del cliente y se actualiza. durante todo el proceso. Hay muchos otros casos de uso y características que proporciona StopLight, pero este puede ser el que ha impactado mi trabajo de manera más significativa.

*Los requisitos y la lista de deseos de Cagan son citas directas de Inspired: How to Build Products Customers Love.