Documentare le API: per quale audience?

Come promesso, ricominciamo da questo grafico:

Come vedete, per le API è possibile approntare diversi tipi di "documentazione" o "informazioni per gli utenti" (secondo la definizone indicata nello standard ISO/IEC/IEEE 82079). Ma è possibile stilare una classifica di "priorità"? Cosa è assolutamente necessario e cosa posso considerare un "nice to have"? Dipende...

Da cosa dipende? Dall'audience ovviamente!

Chi è interessato a capire cosa si può fare con le nostre API?

Banalmente, gli sviluppatori che dovranno utilizzarle per scrivere software. 

Ma prima che uno sviluppatore possa utilizzare delle APIs, vi sono almeno altri due ruoli aziendali che devono intervenire per decidere di spendere il denaro necessario per acquisatre le APIs.

Il Product Manager (PM) ed il Chief Technical Officer (CTO) sono due figure chiave che dovremo convincere ad acquisatre le nostre APIs, e visto che ci saranno altri concorrenti che cercheranno di fare altrettanto dovremo fare le scelte giuste.

Ad esempio, fornire una Reference Guide che spiega nei dettagli ogni aspetto di ogni endpoint delle nostre API sarà molto utile per gli sviluppatori, ma di nessun aiuto per il PM ed il CTO.

La mia esperienza professionale mi suggerisce l'opportunità di segmentare l'audience in questo modo:

• Sviluppatori
• Sviluppatori Interni
• Partners commerciali
• Sviluppatori Clienti
• PM
• CTO

SVILUPPATORI

Gli sviluppatori utilizzeranno le API per scrivere applicazioni software e sono ritenuti i principali clienti per un "API vendor". In questo gruppo possiamo distinguere almeno 3 aree.

SVILUPPATORI INTERNI

Le API vengono usate dagli sviluppatori "esterni" (clienti del software vendor), ma vengono realizzate dagli sviluppatori "interni" del software vendor. Ma gli sviluppatori "interni" hanno bisogno della documentazione sulle API che hanno realizzato? 

Ovviamente si, per il banale motivo che ci crea un gran numero di API non è di certo in grado di ricordare a memoria tutte le loro proprietà, i parametri e i codici di ritorno.

Certo, si può aprire il codice sorgente ed investigare al suo interno... e molti sviluppatori sono abituati ad agire così, ma non è di sicuro il modo più comodo e veloce.

Per gli sviluppatori interni, una Reference Guide è di solito sufficiente.

Molte delle voci che sono presenti nel grafico precedente, fanno parte della Reference Guide.

Ovviamente è necessario anche un Sandbox Environment, cioè un'area dove si possono testare le API e verificarne il funzionamento, ma per gli sviluppatori interni questo è un elemento "nativo".

In sintesi, per gli sviluppatori interni può essere sufficiente definire:

• Reference Guide
• Sandbox Environment

PARTNER COMMERCIALI

I nostri partner commerciali di solito sono sviluppatori esperti che hanno confidenza con le nostre soluzioni e usano le nostre API per progetti di system integration.

In questo caso è necessario fornire gli stessi documenti utilizzati anche dagli SVILUPPATORI INTERNI, ma anche degli esempi di codice che illustrano alcuni casi d'uso tipici e, per ogni API (che può racchiudere diversi endpoint) sarebbe opportuno almeno uno Use Case.

Lo Use Case descrive uno scenario concreto in cui dobbiamo risolvere un problema e indica la soluzione adottata attraverso gli strumenti disponibili; in questo caso, le API che possono essere utilizzate per indirizzare il problema descritto. 

Nello Use Case si indica la sequenza delle operazioni fondamentali da eseguire (per i dettagli si rimanda alla Reference Guide) ed anche un esempio eventuale di codice che utilizza le API in questione.

Se non si dispone della documentazione di uno Use Case, bisogna fornire ALMENO una Getting Started Guide.

Inoltre, i nostri partner devono essere informati quando apportiamo variazioni alle caratteristiche delle nostre API, quindi dobbiamo aver cura di pubblicare un Change Log che sia in grado di descrivere qualsiasi variazione significativa sulla struttura e i parametri delle nostre API.

Ricapitolando, dobbiamo fornire almeno:

• Reference Guide
• Sandbox Environment
• Sample Code
• Use Case
• Getting Started
• Change Log

SVILUPPATORI CLIENTI

Questi sono i nostri interlocutori più preziosi, quelli che possono determinare il successo effettivo delle nostre API. E questi hanno bisogno di TUTTO quello che gli possiamo dare.

Oltre a tutti i documenti già disponibili per i PARTNER COMMERCIALI, per i clienti può essere necessari predisporre un Software Developmnet Kit (SDK) cioè uno strumento software e di documentazione che serve a velocizzare lo sviluppo di applicazioni software.

Ma anche una Troubleshooting Guide, per indirizzare tutte quelle situazioni in cui le nostre API presentano dei limiti applicativi oltre i quali l'applicazione potrebbe non funzionare correttamente.

Ovviamente, va fornito anche un glossario. Le nostre API fanno riferimento a concetti, algoritmi, standard ed acronimi che per noi non hanno segreti, ma per gli sviluppatori dei nostri clienti potrebbero essere criptici. 

Finito? Probabilmente no, ma se siamo riusciti a fornire tutte le informazioni appena descritte, siamo a buon punto. Ricapitolando:

• Reference Guide
• Sandbox Environment
• Sample Code
• Use Case
• Getting Started
• Change Log
• SDK
• Troubleshooting Guide
• Glossary
• ... ALTRO?...

PRODUCT MANAGER

Che lavoro fa il Product Manager? Non semplice da definire in due righe. 

In estrema sintesi, è uno che "indica la via" soprattutto dal punto di vista della collocazione del prodotto sul mercato, e contribuisce (insieme ad altre figure aziendali) a definire le linee guide fondamentali (tecnologia, UX, competition, comunicazione, ...) lungo le quali si deve sviluppare il prodotto; inoltre deve avere una "visione" coerente di tutto ciò (e anche di altri fattori) almeno di medio periodo. 

Bello vero? Si, ma non semplice.

Restringendo il perimetro al nostro caso, il PM deve capire se la tecnologia che gli stiamo proponendo porta un vanataggio nello sviluppo del prodotto e della relativa offerta commerciale, tenendo conto dei diversi fattori sopraindicati. Quindi è chiaro che per lui una Reference Guide o un SDK non sono di nessun interesse.

Se vogliamo conquistare la sua attenzione dobbiamo spiegare il Return of Investement (ROI) Scenario  che può ottenere dalle nostre API. Quali sono gli Use Case sensibili per lui? Quali sono le aree dove le aziende concorrenti sono in questo momento più attrezzate? Noi dobbiamo essere bravi ad assistere i suoi punti deboli, dimostrare che le nostre API vanno a chiudere "il buco" e colmare la distanza rispetto ai concorrenti. O anche che le nostre API sono dei "differenziatori" rispetto a quanto possono offrire i concorrenti.

Un esempio classico  potrebbe essere il White Paper "comparativo", di cui ho scritto nel 2010; si ok, ok, adesso i "puristi" saltano sulla sedia e mi fanno notare che il White Paper è un "documento di marketing" e non è "documentazione tecnica". 

Se siete ancora ancorati a questi schemi, rischiate di non cogliere il punto.

Qui il problema non è attenersi a delle schematizzazioni di maniera, ma risolvere il problema: convincere il PM che le nostre API saranno un valore aggiunto.

Un documento che potrebbe avere punti di contatto con il ROI Scenario, ma più ad "alto livello"  e in una prospettiva di medio periodo potrebbe essere il White Paper "di scenario". 

Ricapitolando:

• ROI Scenario
• Use Case
• White Paper "comparativo"
• White Paper "di scenario"

CTO

Il CTO è la massima autorità tecnico-manageriale di un'azienda ed è il responsabile della strategia di medio-lungo periodo nell'evoluzione del prodotto. Di solito è un manager con un robusto back-ground tecnico. Quindi per convincere il CTO dobbiamo offrire una visione tecnica completa delle nostre API, ma di alto livello.

Quali tecnologie utilizziamo? Quali aree applicative andiamo a coprire? Quali standard tecnici vengono implementati attraverso le nostre API? Quanti potenziali clienti possono giovarsi delle nostre API? Quali difficoltà di integrazione possiamo abbattere? Se possiamo fornire un API Portal quali caratteristiche espone il nostro portale?

Queste sono alcune delle principali domande a cui potremmo dover rispondere per convincere il CTO delle nostre buone ragioni.

Un documento che potrebbe rispondere a questa esigenza è il White Paper "tecnico".

In generale, dovrà essere un documento breve, intenso, con dentro tutti i dati tecnici salienti che dobbiamo trasmettere al CTO per convincerlo a comprare le nostre API. Poi potete accompagnare questo documento con uno Use Case "ad-hoc" che metta in evidenza tutti gli aspetti sopracitati, immersi in un caso concreto.

*****

In questo post ho citato diversi concetti senza spiegarli, ma nei prossimi post di questo ciclo andrò a chiarire con maggior dettaglio. 

A presto!

Condividi

Articoli correlati per categorie