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...

domenica 27 settembre 2020

API "economy": quale impatto sulla Comunicazione Tecnica?

Chi realizza informazioni per gli utenti che devono usare una piattaforma software, almeno una volta nella vita si è trovato a dover produrre documentazione relativa alle Application Programming Interface (API).


Le API sono interfacce che espongono le funzionalità di applicazioni software.

Per interagire con una certa funzione dell'applicazione, non dovete conoscere i dettagli di quest'ultima, ma solo alcuni parametri che dovete "passare" ad una certa API, la quale vi restituirà il risultato previsto da quella funzione.

Volendo generalizzare, un API è formata da un insieme di metodi di comunicazione chiaramente definiti. Attraverso tali metodi è possibile richiedere servizi alla piattaforma software, che sia un sistema operativo o altra applicazione.

Io ricordo di aver iniziato a "documentare API" per la prima volta nel 2003, quindi non sono una novità. Ma perché oggi sono diventate così importanti?

Perché oggi lavoriamo normalmente in ecosistemi digitali complessi ed eterogenei, ospitati da architetture Cloud e basati su standard e tecnologie diverse, attraverso applicazioni web che devono cooperare per scambiare un grande volume di dati.

I sistemi IoT (Internet of Things) producono un grande volume di dati che alimentano i repository di Big Data. I motori di intelligenza artificiale (AI) devono essere addestrati da grandi volumi di dati strutturati e non, estratti dai Big Data. Tutti questi flussi informativi devono essere gestiti da solide politiche di Information Security. 

IoT, Big Data, AI, Information Security e altre aree tecnologiche devono lavorare insieme, collegate attraverso reti di grandi dimensioni e completamente integrate per ottenere funzionalità sempre più sofisticate.

Come realizziamo queste architetture complesse? 

L'unica possibilità è fornire insiemi di API che possano essere utilizzate per integrare diversi sistemi digitali, senza che vi sia la necessità di conoscere la struttura dei singoli sistemi.

L' "API Economy" sta diventando il principale motore dell'attività di digitalizzazione, in qualsiasi settore industriale.

Puoi pensare a un'API come a un "livello" che nasconde la natura del sistema sottostante.
È possibile attivare un'API tramite un breve set di parametri.
Questo set di parametri (numerici o testuali) consente di eseguire un'azione precisa sul sistema.

Non è necessario conoscere il motore interno del sistema o tutti i dettagli sui diversi algoritmi implementati. È sufficiente conoscere il set di API di sistema per gestire tutte le interazioni necessarie.

Oggi scrivere la documentazione che accompagna una piattaforma software significa, principalmente, scrivere la documentazione delle API, cioè tutto quello che serve all'utente per utilizzare le API.

Chi è il nostro utente target in tal caso? Di solito, un programmatore.
Perché le API servono a scrivere il codice che permette di costruire gli strati d'integrazione tra due sistemi eterogenei, e questo lavoro è il lavoro degli sviluppatori software.

Questa osservazione non è banale, perché se dovete scrivere per un programmatore, allora sarà bene avere confidenza con l'attività di scrittura del codice e con i più diffusi linguaggi di programmazione.

E qui si apre un primo fronte nell'eterno conflitto tra due posizioni:
  1. Quelli che... "chi scrive la documentazione del prodotto deve essere un esperto del prodotto..."
  2. Quelli che... "un Comunicatore Tecnico può scrivere la  documentazione di qualsiasi prodotto... anzi meno è esperto di una certa tecnologia e meglio è..."
Non sono mai stato un manicheo e non inizierò oggi.

L'esperienza mi ha insegnato che se non hai confidenza con la tecnologia che devi descrivere, puoi comunque fare un buon lavoro, ma probabilmente impiegherai una quantità di tempo superiore a quella che sarebbe stata necessaria se avessi avuto "le mani in pasta" con quella tecnologia.
E LA VELOCITA' è un valore!
Ma questa è un'altra conversazione che riprenderemo più avanti.

Certamente, nel caso della documentazione di API, è opportuno avere una "profonda confidenza" con la programmazione software e questo è un punto da tenere a mente.

A presto.
Leggi questo articolo...

domenica 14 giugno 2020

Un evento online: Because Online ROADSHOW

Nei giorni 23, 24, e 25 Giugno ci sarà un evento online da non perdere, soprattutto se siete dei professionisti della Comunicazione Tecnica.




In tempi di COVID-19, quando qualsiasi conferenza frontale è stata di fatto neutralizzata, abbiamo scoperto l'utilità dei processi digitalizzati e delle comunicazioni remotizzate.

E il primo ROADSHOW della Because si inserisce perfettamente in questo contesto.

Tre giornate (2 ore e mezza ogni giorno) in cui diversi professionisti del settore si avvicenderanno in uno schema di lavoro molto flessibile per parlare di diversi aspetti:
  • GIORNO 1 (23 Giugno): Creazione di contenuti tecnici
  • GIORNO 2 (24 Giugno): La tecnologia al servizio delle lingue
  • GIORNO 3 (25 Giugno): CCMS & Content Delivery
Io sarò presente il primo giorno e metterò a disposizione il mio punto di vista e la mia esperienza sulle tematiche del processo redazionale.

Vi invito a partecipare perchè occasioni come queste sono rare in Italia, probabilmente uniche, almeno per tutto il 2020.

Vi aspetto.

Leggi questo articolo...

domenica 31 maggio 2020

Comunicazione Tecnica e COVID-19: quali impatti sulla professione

La pandemia mondiale ha avuto un impatto fortissimo su diversi aspetti della nostra vita, e largamente sulla nostra vita professionale.

Il collega Tom Johnson, autore di uno dei più importanti blog sulla scrittura tecnica, ha preso l'iniziativa di costruire un sondaggio al fine di indagare in che modo la professione del Com Tecnico sia stata "tocccata" dal COVID-19.

E i risultati sono molto interessanti.
Ad esempio, durante la pandemia solo il 4.76% dei partecipanti ha perso il proprio lavoro.

Il sondaggio è ancora aperto e vi invito a partecipare. Per ora, l'Italia ha contribuito con due partecipanti su 256 (ed uno dei due sono io).

Come sapete, in Italia non ci sono dati pubblici sulla nostra professione; non si fanno sondaggi tematici di alcun genere, e quindi non abbiamo alcun dato nel contesto nazionale.
Quindi varrebbe la pena partecipare a queste iniziative, per provare a dare un contributo basato sulle esperienze dei professionisti italiani. Leggi questo articolo...