Se esiste un Dio...

 ... forse oggi ha voluto riprendersi la sua "Mano". 

"...perché la vita è un brivido che vola via... 

...è tutto un equilibrio sopra la follia..."

 V.Rossi

Leggi questo articolo...

Volete progettare un Chatbot? Avete bisogno di... una mappa.

Cos' è un chatbot? E' un software in grado di simulare una conversazione, consentendo agli utenti di interagire con applicazioni web e dispositivi digitali, come se il software fosse una persona reale. 

Da alcuni anni se ne parla (spesso "a vanvera"), anche in contesti di associazioni professionali ... poco professionali.

Molti hanno provato a cavalcare l'onda dell'argomento "cool", quello che "fa figo" se in mezzo ad un discorso da salotto pronunci la parola "chatbot" (ma lo stesso vale anche per "blockchain", "machine learning", etc). 

Risultati? Spesso pessimi.

Potete costruire chatbot semplici, magari basati su approcci molto datati, come i "decision-tree" oppure chatbot più flessibili, basati su motori di intelligenza artificiale (AI) e potete progettare sofisticati assistenti digitali personalizzati in diversi settori.

Del resto, se i maggiori player mondiali stanno investendo in piattaforme conversazionali e non da ora, come indica Gartner, significa che esiste un mercato potenziale notevole e ancora disponibile.

Ma non si può improvvisare.

Progettare un chatbot non è roba per apprendisti stregoni e bisogna mettere in campo competenze in diverse aree: 

• Fare un assessment molto approfondito dello use case a cui dobbiamo applicare il chatbot.
• Saper scegliere la piattaforma software per progettare il chatbot.
• Definire il decision-tree o individuare il dataset utile per allenare il motore di AI.
• Saper scrivere contenuti "molecolari" (Information 4.0) in uno stile conversazionale.
• Conoscere i principi del NLP (Natural Language Processing) e del Machine Learning

.... e molto altro ancora.

Insomma, serve prima di tutto una metodologia o se preferite una "mappa".

Se volete avere un'introduzione al metodo di lavoro che necessita per progettare un chatbot, date un occhiata al blog di Technically Write IT, uno dei blog più interessanti nel campo della Comunicazione Tecnica.

Qui potete trovare tre articoli che vi danno"la mappa", inquadrando le questioni essenziali.

Come costruire un buon chatbot chiarisce alcune questioni di background e fornisce una sorta di check-list per capire come costruire la vostra content strategy, adattata allo use case che dovete indirizzare.

Come realizzare contenuti efficaci per un chatbot fornisce gli step principali per definire contenuti conversazionali del vostro chatbot e gestire il workflow di progettazione.

Come scegliere una piattaforma per sviluppare un chatbot indica le principali caratteristiche che deve avere una valida piattaforma software e anche un elenco delle più importanti piattaforme oggi disponibili sul mercato.

A questo punto siete in grado di progettare un chatbot? 

ASSOLUTAMENTE NO!... ma avete una "mappa" che vi guida a valutare tutti i passaggi fondamentali per poter progettare un chatbot e che vi permetterà di risparmiare tempo ed evitare gli errori più banali.

A presto.

Leggi questo articolo...

Documentare le API: bisogna avere un background tecnico?

Il post precedente ha iniziato ad indagare più in profondità la tematica di come documentare le API.

Se avete avuto la pazienza di leggerlo, secondo me nella vostra testa si è accesa una lampadina, la tipica lampadina che precede la formulazione di una serie di domande:

• Chi documenta le API deve avere confidenza con lo sviluppo software? 
• Deve saper leggere un frammento di codice scritto in Java o in C++ o in Phyton? 
• Deve saper leggere dentro un oggetto JSON o protobuffer? 
• Deve saper navigare agevolmente dentro un XML? 
• Deve conoscere i codici di ritorno del protocollo HTTP?
• Deve aver confidenza con la gestione di processi di sviluppo Agile e Continous Delivery?
• E, più in generale, deve avere un background tecnico solido?
• In altri termini: deve governare almeno i fondamentali della programmazione o essere addirittura un ex-programmatore? 

La mia risposta è SI!

Mentre un technical writer della "scuola classica" potrebbe sostenere che "il technical writer non deve essere esperto della tecnologia da documentare, anzi proprio per questo sarà più efficace nel suo lavoro".

In teoria, possiamo amabilmente discutere di tutto.

In concreto, la mia esperienza mi dice che in certi ambiti tecnologici, il comunicatore deve avere "le mani in pasta" rispetto alla tecnologia. Forse è eccessivo sostenere che debba addirittura essere un ex-programmatore, ma deve di certo padroneggiare tutte le necessarie conoscenze.

Questo è tanto più vero quanto più siamo immersi dentro flussi di lavoro Agile, che alimentano processi di Continous Delivery, dove i tempi di sviluppo della documentazione sono indistinguibili dal ciclo di sviluppo del software e sono estremamente "strettti". 

In tali contesti, con cicli di lavoro di 3 settimane, non c'è molto tempo per "intervistare gli SME", produrre 2 o 3 draft da validare, fare la review linguistica/terminologica, sviluppare la grafica a supporto ed altri passaggi classici dei processi di documentazione.

O meglio: si DEVE FARE tutto questo ma molto più velocemente, in "presa diretta", senza rete. E con molta più "qualità intrinseca", proprio perchè c'è meno tempo anche per rimediare agli errori.

Questo ci obbliga a dover avere una certa "conoscenza" della tecnologia che stiamo documentando, perchè questo ci permette di essere più veloci... e la velocità è un valore.

Non siete convinti? 

Mi avvalgo ancora del report di SmartBear per darvi ulteriori elementi.

QUALI SONO I MAGGIORI OSTACOLI ALLA PRODUZIONE DI API DI QUALITA'?

Le prime due risposte, con il 52% e il 48% delle risposte, vanno a coprire esattamente la mia tesi.

Se non foste convinti, anche la 3^ e la 4^ risposta vanno nella stessa direzione.

Le prime 4 risposte influenzano notevolmente anche i processi di documentazione tecnica.

Le risposte dalla 5^ alla 7^ invece sono più incentrate sull'integrazione di tools, sistemi e processi aziendali.

Tutte queste risposte evidenziano che la qualità delle API prodotte nel nostro processo aziendale, che coinvolge anche la relativa documentazione, ruotano su due elementi principali:

• La competenza e l'esperienza tecnica specifica.
• La velocità di esecuzione del delivery (o se preferite i tempi di realizzazione sempre molto ridotti tra due rilasci successivi).

Se volete avere un primo contatto con il paradigma "Docs as Code" che sintetizza le idee che vi ho illustrato in questo post, date un occhio a questa miniera d'oro di spunti.

A presto.

Leggi questo articolo...

Documentare le API: ci sono diversi tipi di API...

Nei primi 3 articoli di questa serie, ho provato a definire "la cornice" di una tematica complessa:

1. Api "economy": quale impatto sulla Comunicazione Tecnica?
2. Documentare le API? Le risposte nascono dalle domande...
3. Documentare le API: per quale audience?

Ora provo ad analizzare "il quadro", che è composto da diverse aree in relazione tra di loro, come in un quadro di Mondrian:

Prima di tutto, cominciamo a distinguere tra i diversi tipi di API che potremmo ritrovarci a dover documentare.

Riprendiamo lo spunto dal report di SmartBear.

Il grafico indica i tipi di API oggetto di attenzione tra i partecipanti al sondaggio:

CLASSIFICAZIONE DELLE API

Di seguito, vi fornisco una breve panoramica delle tipologie di API più diffuse.

Se volete approfondire ogni singola area, potete trovare del materiale in rete a partire dai link che vi segnalo.

In un prossimo blocco di articoli andrò ad approfondire le questioni di documentazione inerenti alle REST API, che sono oggi prevalenti sul mercato. Ma vedremo che i concetti generali e le best practice sono applicabili anche fuori dal perimetro delle REST API, con eventuali adattamenti.

REST API

Nell'architettura REST (REpresentational State Transfer), il server non memorizza lo stato della sessione del client. Ogni richiesta HTTP dal client al server deve contenere tutte le informazioni necessarie (payload) e lo stato della sessione è mantenuto lato client. Il server non si basa sulle informazioni provenienti da richieste precedenti. Il client è responsabile dell'archiviazione e della gestione di tutte le informazioni relative allo stato dell'applicazione.

Le REST API utilizzano diversi formati di dati tra cui TXT,  XML e JSON. L'utilizzo di formati di dati più semplici rende i payload più leggeri, il che rende le API REST più adatte a una gamma più ampia di applicazioni.

Ad esempio, REST API con payload JSON sono molto utilizzate in integrazioni IoT, dove diversi tipi di dispositivi, non sempre dotati di grandi capacità di memoria e di calcolo, devono scambiarsi informazioni.

Attraverso una REST API ci si relaziona con una "risorsa", identificata da una URL. I "consumatori" inviano richieste GET per accedere ad una risorsa e richieste PUT, POST e DELETE per modificarla o cancellarla.

SOAP API - WSDL

Le SOAP API (Simple Object Access Protocol) sono servizi Web che si basano su un protocollo XML per definire il formato dei messaggi delle richieste e delle risposte. Il formato dei messaggi XML di SOAP viene solitamente definito tramite un file WSDL (Web Services Description Language) che specifica gli elementi e gli attributi consentiti nello scambio di messaggi. 

Il file WSDL è leggibile dalla macchina e utilizzato dai server che interagiscono tra loro per facilitare la comunicazione. 

Un file WSDL può potenzialmente descrivere un formato del messaggio di notevole complessità.

Questo è il motivo essenziale per il quale le REST API stanno soppiantando le SOAP API in tutte le applicazioni dove non necessita una comunicazione particolarmente strutturata, quindi dove si può anche fare a meno dell'XML.

RPC API

Le RPC API (Remote Procedure Call) sono servizi Web che chiamano un metodo su un server remoto fornendo un messaggio codificato in HTTP. Il formato del messaggio codificato potrebbe essere XML (API XML-RPC) o JSON (API JSON-RPC), in entrambi i casi via HTTP come altri servizi web. Queste API sono agnostiche rispetto la linguaggio di programmazione (Java, Python, C ++, ...) con cui viene realizzato il metodo remoto.

gRPC API

Le gRPC API, sviluppate da Google, sono servizi web simili alle RPC API basate su RPC. gRPC definisce i messaggi non in formato XML o JSON ma attraverso un buffer, specificato attraverso un file con estensione .proto. Il buffer.proto  consente di definire la struttura dei dati e il modo in cui serializzare i dati che devono essere consumati dal server ricevente. Il formato "protobuffer" è considerato più leggero efficiente rispetto ad XML.

GraphQL

Le GraphQL API sono servizi web sviluppati da Facebook che consentono un'interazione dinamica basata su un unico endpoint. La query GraphQL recupera solo i dati necessari, consentendo richieste e risposte veloci.

Async API

AsyncAPI è uno standard open source mirato alle architetture basate su eventi (Event Driven Architecture). Simile alla specifica OpenAPI, consente di definire un'interfaccia comune per le interfacce EDA e consente una gestione multicanale. Quindi la stessa specifica può essere utilizzata per un API basata su MQTT o per una API Kafka.

AsyncAPI si basa su due concetti:

• i messaggi guidano la maggior parte delle interazioni API
• questi messaggi descrivono azioni o eventi. 

In sostanza, AsyncAPI crede che tutto possa essere rappresentato come un sistema di messaggi, con un'intestazione e un payload facoltativi o non richiesti. In questa visione, AsyncAPI cerca di abilitare la definizione di API utilizzando definizioni basate sul canale indipendenti dal protocollo.

Librerie di API

Le "API basate su libreria", si riferiscono a librerie di codice (ad esempio, file JAR) che gli sviluppatori aggiungono direttamente ai loro progetti per fornire funzionalità aggiuntive tramite classi e metodi (nel caso di linguaggi ad oggetti come Java, .NET stack, C++) o altre funzioni che possono essere chiamate localmente. Con le API della libreria nativa, le funzioni sono incorporate localmente all'interno del codice per potenziare le operazioni realizzate dall'applicazione. Questo tipo di API sono strutturalmente diverse rispetto alle Web API che abbiamo elencato in precedenza.

Un esempio? OpenSSL API, cioè la più importante libreria crittografica open source.

----------------------------------------------

ABBIAMO FINITO? Ovviamente no. 

Ci sono altri tipi di API che potremmo dover documentare? Certo.

Allora diciamo che sono abbastanza confidente di avervi fornito "una mappa di base" per iniziare ad orientarvi rispetto alle caratteristiche generali delle API che attualmente coprono, ragionevolmente, il 90% dei casi che potreste dover gestire.

A presto.

Leggi questo articolo...

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

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

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

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

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