Utilizzo di un prototipo come specifica di prodotto API

In qualità di Developer Experience Product Manager di SendGrid, ho il compito di identificare opportunità, funzionalità e prodotti che coinvolgono la nostra API. Una cosa su cui ho lavorato è l'identificazione dei metodi per rendere più efficace la comunicazione delle mie idee di prodotto agli altri PM, ingegneri e clienti.

Ho imparato che un documento sui requisiti di prodotto (PRD) monolitico è un modo tutt'altro che ideale per farlo e che un'interfaccia testabile che includa le stesse informazioni di una specifica del prodotto sarebbe una potente alternativa. Il problema con i PRD è che spesso sono molto grandi e per lo più di testo. È troppo facile perdere il tuo posto o perdere qualcosa di veramente importante.

I nostri amici in UX hanno risolto questo problema con strumenti come Invision , dove forniscono un'interfaccia cliccabile che puoi toccare e utilizzare, piuttosto che un documento o wireframe che descrive semplicemente l'interfaccia. Poiché un'API è un'interfaccia, abbiamo bisogno di uno strumento che consenta l'interazione con la specifica in tempo reale, piuttosto che un insieme di testo descrittivo e JSON in un documento.

Definizione dei requisiti

Come dovrebbe essere questa interfaccia testabile come specifica del prodotto? Come funzionerebbe? Esiste?

Mentre stavo leggendo il capitolo 18, "Reinventing the Product Spec", di Marty Cagan's Inspired: How to Build Products Customers Love , mi sono reso conto che volevo condividere uno strumento che stavo usando che soddisfa i requisiti di Cagan per una specifica di prodotto, la maggior parte di la sua lista dei desideri per le specifiche del prodotto e il mio elenco personale di requisiti per il prototipo come specifica.

Requisiti di Cagan*:

• Le specifiche devono descrivere l'esperienza utente completa.
• Le specifiche devono rappresentare accuratamente il comportamento del software.
• Devi essere in grado di comunicare il prodotto in modo che tutte le parti interessate ottengano ciò di cui hanno bisogno.
• Le specifiche cambieranno
• È necessario che ci sia un'unica rappresentazione principale delle specifiche per ridurre ambiguità e versioni.

La lista dei desideri di Cagan*:

• Dovrai integrare il prototipo [con]:
  • Logica di business
  • Requisiti di rilascio
  • Requisiti di consegna della piattaforma
  • Casi d'uso
• Voglio davvero essere in grado di annotare il prototipo

I miei requisiti per il prototipo come specifica:

• Il prototipo dovrebbe essere la specifica.
• La documentazione dovrebbe essere integrata nel prototipo.
• Tutti nell'azienda che ne hanno bisogno dovrebbero avere accesso al prototipo e alla documentazione.
• Il cliente dovrebbe essere in grado di accedere alla parte funzionale del prototipo per il test dell'utente.
• Il prototipo dovrebbe sostituire le specifiche e funzionare il più vicino possibile alla funzionalità prevista senza cablare un prodotto finito.
• Dovrebbe essere facile apportare e registrare le modifiche al prototipo.
• Dovrebbe essere facile apportare variazioni A/B che possono essere testate da chiunque abbia accesso al prototipo.
• Dovrebbe essere facile esportare la documentazione del cliente dal prototipo.

Presentazione di StopLight

Lo strumento che ho usato che soddisfa quasi tutto quanto sopra si chiama Stoplight.io . È al suo interno un motore di documentazione API e un proxy web. Ti consente di definire la tua API utilizzando un'interfaccia utente intuitiva, che ha il meglio di Swagger e RAML dietro le quinte come motore di specifiche insieme alla possibilità di importare o esportare da entrambi i formati.

Poiché StopLight è uno strumento di documentazione, puoi definire le richieste, le risposte, le intestazioni e le descrizioni per i tuoi endpoint. Con la funzione proxy, puoi chiamare la tua API e verificare che le tue chiamate corrispondano alle tue specifiche o scoprire automaticamente i tuoi endpoint per ottenere la maggior parte della tua documentazione scritta automaticamente.

Il proxy di StopLight ha anche molte altre caratteristiche assolutamente sorprendenti:

• La possibilità di effettuare chiamate fittizie ai tuoi endpoint se il tuo prodotto non è finito o se non vuoi inoltrare le tue richieste.
• Server locale per testare il tuo prototipo sulla tua macchina.
• Server remoto per testare il tuo prototipo su Internet.
• Middleware, scritto in Javascript, per la definizione del codice che può essere eseguito prima e/o dopo la chiamata degli endpoint del prototipo.

Se confronti la combinazione della mia lista dei desideri, dei requisiti delle specifiche di Cagan e della sua lista dei desideri con le funzionalità fornite da StopLight, puoi vedere che StopLight soddisfa ogni esigenza e desiderio:

• Documentazione solo interna del prototipo e delle sue caratteristiche.
• Un prototipo completo della funzionalità facilmente accessibile.
• Un'interfaccia testabile che ha la capacità di attivare/disattivare le funzioni variabili per il test e il feedback degli utenti.
• Un modo semplice per eseguire la versione del tuo prototipo per una conversazione specifica, in modo da poter modificare la funzionalità del prototipo quasi in tempo reale per illustrare e verificare il feedback che hai ricevuto.

Il flusso di lavoro in StopLight è semplice e può essere eseguito da chiunque , indipendentemente dalle proprie capacità tecniche:

• Crea un nuovo progetto.
• Aggiungi la specifica facendo clic e digitando le informazioni sull'endpoint, i suoi parametri, la richiesta e la risposta.
• Aggiungi le informazioni sulle specifiche del tuo prototipo nella schermata Definizione.
• Se disponi di funzionalità opzionali, aggiungile utilizzando il middleware.
• Attiva la presa in giro.
• Copia/incolla l'URL pubblico del server fittizio e condividilo per un feedback.

Se stai visitando un cliente e desideri sperimentare il prototipo in tempo reale, scarica semplicemente la definizione sul tuo computer, crea un nuovo progetto che prende il nome dalla tua visita e importa la definizione. Ora puoi cambiare tutto quello che vuoi senza cambiare il tuo prototipo originale. Quando torni a unire le idee, è facile apportare modifiche come lo è stato costruire il prototipo in primo luogo.

In qualità di Developer Experience Product Manager, StopLight non solo mi sta aiutando a svolgere il mio lavoro in modo più efficiente, è semplicissimo da usare e semplifica le fasi di preparazione della consegna della documentazione dell'API poiché la documentazione è stata avviata prima delle fasi di convalida del cliente e viene aggiornata durante tutto il processo. Ci sono molti altri casi d'uso e funzionalità forniti da StopLight, ma questo potrebbe essere quello che ha avuto un impatto più significativo sul mio lavoro.

*I requisiti e la lista dei desideri di Cagan sono citazioni dirette da Inspired: How to Build Products Customers Love.