Utilizarea unui prototip ca specificație de produs API

În calitate de manager de produs pentru experiența dezvoltatorului la SendGrid, am sarcina de a identifica oportunitățile, caracteristicile și produsele care implică API-ul nostru. Un lucru la care am lucrat este identificarea metodelor care să facă mai eficientă comunicarea ideilor mele de produse către ceilalți PM, ingineri și clienți.

Am învățat că un document monolitic privind cerințele produsului (PRD) este o modalitate mai puțin decât ideală de a face acest lucru și că o interfață testabilă, care să includă aceleași informații ca și specificația produsului, ar fi o alternativă puternică. Problema cu PRD-urile este că acestea sunt adesea foarte mari și mai ales text. Este prea ușor să-ți pierzi locul sau să ratezi ceva cu adevărat important.

Prietenii noștri din UX au rezolvat această problemă cu instrumente precum Invision , unde oferă o interfață pe care se poate face clic pe care o puteți atinge și utiliza, mai degrabă decât un document sau un cadru fir care descrie pur și simplu interfața. Deoarece un API este o interfață, avem nevoie de un instrument care să permită interacțiunea cu specificația în timp real, mai degrabă decât o grămadă de text descriptiv și JSON într-un document.

Definirea cerințelor

Cum ar trebui să arate această interfață testabilă ca specificație de produs? Cum ar funcționa? Există?

În timp ce citeam capitolul 18, „Reinventarea specificațiilor produsului”, din lucrarea lui Marty Cagan Inspired: How to Build Products Customers Love , mi-am dat seama că vreau să împărtășesc un instrument pe care l-am folosit, care satisface cerințele Cagan pentru o specificație de produs, majoritatea lista lui de dorințe pentru specificațiile produsului și propria mea listă personală de cerințe pentru prototip ca specificație.

Cerințele lui Cagan*:

• Specificația trebuie să descrie experiența completă a utilizatorului.
• Specificația trebuie să reprezinte cu exactitate comportamentul software-ului.
• Trebuie să fiți capabil să comunicați produsul într-un mod în care toate părțile interesate să obțină ceea ce au nevoie.
• Specificațiile se vor schimba
• Trebuie să existe o singură reprezentare principală a specificației pentru a reduce ambiguitatea și versiunea.

Lista de dorințe a lui Cagan*:

• Va trebui să completați prototipul [cu]:
  • Logica de afaceri
  • Cerințe de lansare
  • Cerințe de livrare a platformei
  • Cazuri de utilizare
• Îmi doresc foarte mult să pot adnota prototipul

Cerințele mele pentru prototip ca specificație:

• Prototipul ar trebui să fie specificația.
• Documentația ar trebui să fie integrată în prototip.
• Toți cei din companie care au nevoie de el ar trebui să aibă acces la prototip și documentație.
• Clientul ar trebui să poată accesa partea funcțională a prototipului pentru testarea utilizatorului.
• Prototipul ar trebui să înlocuiască specificațiile și să funcționeze cât mai aproape de funcționalitatea dorită, fără a conecta un produs finit.
• Ar trebui să fie ușor să faci și să înregistrezi modificări la prototip.
• Ar trebui să fie ușor să faci variații A/B care să poată fi testate de oricine are acces la prototip.
• Ar trebui să fie ușor să exportați documentația clientului de pe prototip.

Vă prezentăm StopLight

Instrumentul pe care l-am folosit și care satisface aproape totul de mai sus se numește Stoplight.io . Este în esență un motor de documentare API și un proxy web. Vă permite să vă definiți API-ul folosind o interfață de utilizare intuitivă, care are în culise cele mai bune din Swagger și RAML ca motor de specificații, împreună cu capacitatea de a importa sau exporta din oricare format.

Deoarece StopLight este un instrument de documentare, puteți defini solicitările, răspunsurile, anteturile și descrierile pentru punctele dvs. de terminare. Cu funcția de proxy, puteți apela API-ul și verifica dacă apelurile dvs. corespund specificațiilor dvs. sau puteți descoperi automat punctele finale pentru a obține cea mai mare parte a documentației scrise automat.

Proxy-ul StopLight are și alte câteva caracteristici absolut uimitoare:

• Posibilitatea de a face apeluri simulate către punctele dvs. finale dacă produsul dvs. nu este finalizat sau nu doriți să trimiteți cererile dvs. prin proxy.
• Server local pentru testarea prototipului pe mașina dvs.
• Server la distanță pentru testarea prototipului dvs. pe Internet.
• Middleware, scris în Javascript, pentru definirea codului care poate rula înainte și/sau după apelarea punctelor finale ale prototipului dvs.

Dacă comparați combinația dintre lista mea de dorințe, cerințele de specificații ale lui Cagan și lista de dorințe cu funcționalitatea oferită de StopLight, puteți vedea că StopLight satisface fiecare nevoie și dorință:

• Documentație internă a prototipului și a caracteristicilor acestuia.
• Un prototip complet ușor accesibil al funcționalității.
• O interfață testabilă care are capacitatea de a comuta funcții variabile pentru testarea și feedbackul utilizatorului.
• O modalitate ușoară de a versiunea prototipului pentru o anumită conversație, astfel încât să puteți modifica funcționalitatea prototipului aproape în timp real pentru a ilustra și a verifica feedback-ul pe care l-ați primit.

Fluxul de lucru în StopLight este simplu și poate fi realizat de oricine , indiferent de capacitatea sa tehnică:

• Creați un nou proiect.
• Adăugați specificația făcând clic și tastând informații despre punctul final, parametrii acestuia, cererea și răspunsul.
• Adăugați informații despre specificații despre prototipul dvs. în ecranul Definiție.
• Dacă aveți caracteristici opționale, adăugați-le folosind middleware-ul.
• Activați batjocorirea.
• Copiați/inserați adresa URL publică a serverului batjocoritor și partajați-o pentru feedback.

Dacă mergeți la o vizită la client și doriți să experimentați cu prototipul în timp real, pur și simplu descărcați definiția pe computer, creați un nou proiect numit după vizita dumneavoastră și importați definiția. Acum puteți schimba orice doriți fără să vă schimbați prototipul original. Când te întorci și îmbină idei, este la fel de ușor să faci modificări precum a fost să construiești prototipul în primul rând.

În calitate de manager de produs pentru experiența dezvoltatorului, StopLight nu numai că mă ajută să-mi fac treaba mai eficient, ci este foarte simplu de utilizat și face pașii de pregătire a livrării de documentare a API-ului ușor, deoarece documentația a fost începută înainte de etapele de validare a clienților și este actualizată. pe tot parcursul procesului. Există multe alte cazuri de utilizare și caracteristici pe care StopLight le oferă, dar aceasta poate fi cea care mi-a afectat cel mai mult munca.

*Cerințele și lista de dorințe ale lui Cagan sunt citate directe din Inspired: How to Build Products Customers Love.