lunedì 19 ottobre 2020

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!

Leggi questo articolo...

mercoledì 14 ottobre 2020

Documentare le API? Le risposte nascono dalle domande...

Come detto in precedenza, le API sono la pietra angolare della trasformazione digitale che sta attraversando tutte le aziende. Se non foste convinti di questo assunto, vi basti pensare alle conseguenze della pandemia COVID-19 che stiamo vivendo: quale impatto abbiamo registrato sui processi lavorativi?

Le aziende più efficienti hanno fatto fronte alle difficoltà con meno danni  e sono quelle che dispongono di processi digitalizzati realizzabili senza la necessità che TUTTI i lavoratori siano necessariamente presenti nel perimetro aziendale.

Un esempio? Ai primi di Giugno mi chiama il responsabile della documentazione aziendale di un'importante azienda italiana, di cui non farò il nome.

Il suo problema: a seguito della pandemia, i clienti richiedevano training digitalizzati, da fruire attraverso piattaforme LMS (Learning Management Systems) e lui voleva produrrre degli oggetti SCORM a partire dalla documentazione di prodotto, scritta secondo lo standard DITA.

Prima della pandemia, l'azienda forniva sessioni di training face-to face, ma non era più possibile; tuttavia, la necessità di fornire training ai clienti era pressante. 

Ragionando su questo problema, l'azienda in questione si è resa conto che era conveniente intraprendere questa trasformazione INDIPENDENTEMENTE dalla pandemia!

Al netto della soluzione che ho suggerito, il nocciolo della questione è: possiamo ridefinire e digitalizzare processi non solo perchè siamo obbligati dalle circostanze ma perchè è SEMPLICEMENTE CONVENIENTE! 

E questo fa la differenza nell'era della "API economy".

Se le API sono la spina dorsale dei processi di digitalizzazione, non ci vuole un'intelligenza cartesiana per capire quale ruolo può giocare la Comunicazione Tecnica incentrata sulle API.

Per inizare questo percorso, voglio partire dai dati prodotti da una recente indagine condotta da SmartBear.

Io analizzerò solo alcuni aspetti del report (per una lettura completa, potete accedere da qui).


SETTORI INDUSTRIALI COINVOLTI NELL'INDAGINE











Tutti i maggiori settori industriali sono coinvolti e non solo il settore ICT, che ovviamente fa la parte del leone col 28%.


DA QUANTO TEMPO STATE SVILUPPANDO API?

Questa domanda mostra che solo il 18% delle aziende che hanno partecipato al sondaggio stanno sviluppando API da almeno 10 anni, mentre il 29% sta intraprendendo questa strada da 3-5 anni.

Quindi è un'area di sviluppo ancora molto giovane.









PER QUALI MOTIVI STATE SVILUPPANDO API?

Questa è una delle domande  "chiave" del sondaggio, perchè ci da una panoramica delle motivazioni e ci trasmette un dato essenziale: sviluppare API non è "una moda", una specie di "picco" tecnologico frutto di una momentanea espressione del mercato, ma qualcosa destinato a durare da qui ai prossimi 10-15 anni, che nel campo ICT equivale ad un'era geologica!

Come vedete, prevalgono le motivazioni di interoperabilità tra sistemi diversi (64%) e la capacità di estendere una funzionalità nell'ottica di una logica "a servizi" (53%), sullo sfondo di un più generale processo di trasformazione digitale (43%).

Tutte queste motivazioni (e le altre comprese nel grafico) si alimentano a vicenda, in una sinergia che tenderà a crescere nei prossimi anni.


QUALI PARAMETRI DETERMINANO IL SUCCESSO DI UNA API?

E qui iniziamo ad entrare nell'ambito che più ci interessa, cioè nel delineare come la Comunicazione Tecnica viene coinvolta in questo fenomeno. Nella prossima figura ho evidenziato una voce:










E' evidente che se parliamo di Usability/developer experience, questa voce è largamente influenzata dalla documentazione che accompagna l'API. Ma non cadiamo nel luogo comune per il quale la documentazione delle API è ad uso e consume esclusivo degli sviluppatori: vedremo prossimamente che non è proprio del tutto vero.

Ora tralasciamo altri dati interessanti ma più focalizzati sullo specifico dello sviluppo software e continuiamo ad investigare alcuni aspetti della documentazione delle API, un elemento critico nel ciclo di vita delle API. La documentazione può fare la differenza tra una API di successo ed una inusabile.


IN AZIENDA ESISTE UN PROCESSO PER LA DOCUMENTAZIONE DI API?












Dal grafico si capisce chiaramente che, indipendentemente dalla dimensione dell'azienda, esistono processi dedicati alla documentazione delle API almeno nel 57% dei casi (26-100 dipendenti), per arrivare al 69% nelle grandi organizzazioni. Vi è poi circa un terzo delle aziende "piccole" (e circa un quarto delle aziende maggiori) che sta pianificando l'adozione di processi di documentazione delle API.

Ma ora entriamo a "gamba tesa" sul tema che ci interessa: cosa significa documentare un API?


LE 5 COSE PIU' IMPORTANTI PER DOCUMENTARE UN API














Come vedete esistono almeno 16 "tipologie" diverse di "elementi" attraverso i quali si può articolare la documentazione delle API. E sottolineo ALMENO perchè in realtà potremmo aggiungere qualche altra voce. 

Se un'azienda fornisse ai propri clienti una documentazione strutturata attraverso tutti questi elementi, sarebbe di certo da considerare un'azienda "virtuosa". 

In molti casi, sarebbe ottimale indirizzare anche solo alcuni di questi elementi.

Nel prossimo post, ripartiremo dall'ultimo grafico.

A presto!


Leggi questo articolo...

martedì 6 ottobre 2020

DITA events: occasioni A COSTO ZERO da non perdere!

Oggi inizia Adobe DITA World 2020.

E' uno dei maggiori eventi mondiali online nel campo della Comunicazione Tecnica e il maggior evento in assoluto per quanto concerne lo standard DITA.

Come sapete, DITA è lo standard aperto per la strutturazione dei contenuti più diffuso al mondo. Questa è l'occasione più importante che avete per toccare con mano lo "stato dell'arte".

L'evento si struttura su tre giornate ed è animato dai maggiori esperti mondiali del settore.

Nel 2018 ebbi l'onore di essere tra gli speaker e fu un'esperienza eccezionale.

Vi consiglio di iscrivervi, anche perchè gli iscritti possono poi visionare tutti gli interventi con comodo e non necessariamente in direttta.

MA NON E' FINITA QUI!

In data 8 Ototbre 2020, vi segnalo anche  il DCL DITA Day 2020, altro grande evento online sullo standadrd DITA.

ENTRAMBI GLI EVENTI SONO GRATUITI!

Se volete capire l'evoluzione di questo standard, potrete imparare moltissimo in soli 3 giorni.

Registratevi, e ci vediamo in chat durante gli eventi! A presto!

Leggi questo articolo...