domenica 28 novembre 2021

Sta per uscire la nuova versione dello standard ISO/IEC/IEEE 26514

E' in via di pubblicazione la nuova versione dello standard ISO/IEC/IEEE 26514.

Probabilmente sarà disponibile nei primi giorni di Gennaio 2022, dopo un processo di revisione partito nel Luglio del 2019.

26514 è lo standard per i progettisti e gli sviluppatori delle informazioni per gli utenti che accompagnano un prodotto software. 

Erroneamente si potrebbe pensare che sia applicabile solo ai prodotti software. In realtà, la gran parte dei concetti esposti si può applicare anche alla gestione dei processi di documentazione di un qualsiasi prodotto.

Lo standard descrive principalmente:

  • Come stabilire di quali informazioni hanno bisogno gli utenti.
  • Come definire la presentazione delle informazioni.
  • Come preparare le informazioni e renderle disponibili.
La prima parte è dedicata alla descrizione di quello che io chiamo "il processo redazionale", cioè il processo di pianificazione e gestione della produzione delle informazioni.

La seconda parte riguarda invece la realizzazione e la presentazione delle informazioni.

In questo nuovo standard si fa riferimento in diversi punti allo standard EN IEC/IEEE 82079-1:2020, lo standard orizzontale per la definizione delle informazioni associate al prodotto, per qualsiasi tipo di prodotto (quindi anche per i prodotti software).

Eliminando una serie di sovrapposizioni tra il vecchio standard 26514 e il più recente 82079, è stato possibile definire una nuova versione molto più "snella" dello standard 26514.

La prima versione dello standard era stata pubblicata nel 2008, ed era quindi necessario un aggiornamento che includesse le linee guida di base inerenti ad una serie di nuovi argomenti.

Ritornerò sul punto con un articolo molto più dettagliato quando lo standard verrà pubblicato.

Per ora, volevo solo alzare una bandierina per avvisarvi.

Leggi questo articolo...

giovedì 24 giugno 2021

Pubblicata la bozza del Regolamento Macchine: tra le molte novità, cybersecurity e istruzioni in formato elettronico.

In data 21 aprile 2021 è stata pubblicata la bozza della proposta del nuovo Regolamento Macchine che andrà a sostituire l’attuale Direttiva Macchine 2006/42/CE.

La prima grande novità è la scelta di passare da una Direttiva ad un Regolamento.

Una Direttiva richiede il recepimento del legislatore nazionale, cioè richiede una legge nazionale che renda esecutiva la Direttiva Europea. Un Regolamento è un atto legislativo dell’Unione Europea DIRETTAMENTE applicabile in ciascuno degli Stati membri.

Questo nuovo Regolamento nasce per:

  • Armonizzare i requisiti di salute e sicurezza relativi alla progettazione, alla costruzione e al commercio dei macchinari all’interno della UE.
  • Eliminare le differenze di applicazione tra i diversi Stati membri, che possono adottare diverse strategie nel recepimento della Direttiva.
  • Superare gli evidenti limiti della Direttiva nella gestione di una serie di aspetti associati alle nuove tecnologie.

Nel seguito un breve elenco degli aspetti salienti, con qualche considerazione di scenario, lasciando i maggiori dettagli ad una lettura necessariamente più approfondita della bozza (55 pagine).

APPLICAZIONE DEL NUOVO REGOLAMENTO MACCHINE

Il Regolamento Macchine entrerà in vigore il ventesimo giorno dopo la sua pubblicazione e verrà applicato dopo ulteriori 30 mesi. Ad oggi, si può cautamente ipotizzare che l'iter di pubblicazione del Regolamento possa essere completato entro il primo trimestre del 2022.

L’attuale Direttiva 2006/42/CE sarà abrogata nel momento in cui entrerà in vigore il Regolamento, ma sarà ancora possibile immettere sul mercato macchine conformi alla Direttiva per ulteriori 42 mesi dopo la data di entrata in vigore del Regolamento.

Le violazioni del Regolamento sono soggette a sanzioni stabilite dagli Stati membri, in base a criteri che dovranno essere comunicati alla Commissione entro 24 mesi dall’entrata in vigore del nuovo Regolamento.

OPERATORI ECONOMICI: IMPORTATORE E DISTRIBUTORE

Oltre al COSTRUTTORE, figura già delineata nella Direttiva, entrano in gioco l'IMPORTATORE e il DISTRIBUTORE.

L’IMPORTATORE è il soggetto che immette sul mercato UE un prodotto proveniente da un paese terzo. Deve assicurarsi che il fabbricante abbia completato le procedure per la valutazione della conformità del prodotto e deve specificare sul prodotto i propri dati identificativi; quindi, l’importatore diventa responsabile della conformità del prodotto e ne risponde in prima persona.

L'introduzione di questo profilo di responsabilità avrà, probabilmente, un impatto anche sulla qualità della documentazione tecnica che accompagna il prodotto e che deve essere conservata per 10 anni.

Il DISTRIBUTORE è un soggetto, distinto dal fabbricante o dall’importatore, che provvede a mettere il prodotto sul mercato. Il suo profilo di responsabilità è meno accentuato, ma deve verificare:

  • Che il prodotto sia correttamente identificato (compresi i riferimenti del fabbricante e dell’eventuale importatore).
  • Che la documentazione del prodotto sia presente.
  • Che il prodotto non sia stato oggetto di eventi (durante il trasporto o l'immagazzinamento) che possano aver compromesso la conformità dei requisiti di sicurezza.

DOCUMENTAZIONE DEL PRODOTTO

Altra novità: la documentazione che accompagna il prodotto potrà essere fornita in formato digitale, ad esempio rendendola disponibile su un sito web o su un supporto ad-hoc, ad esempio un USB Key. L’utilizzatore potrà però richiedere, al momento dell’acquisto, una copia cartacea che dovrà essere fornita gratuitamente.

Su questo punto, molte organizzazioni hanno stimolato la Commissione Europea.

L'Advisory Board for Legislation and Standards della tekom Europe, di cui faccio parte, ha espresso il suo orientamento nella direzione di una necessaria revisione della vecchia Direttiva, prevalentemente nell'ambito dei criteri per la produzione della documentazione che accompagna il prodotto.

La tekom Europe, congiuntamente con altre organizzazioni, ha presentato un Position Paper ufficiale, focalizzato proprio sulle istruzioni per l'uso in formato elettronico.

COMPONENTI DI SICUREZZA

Altra notevole novità: nella definizione di “componente di sicurezza” del nuovo Regolamento, sono stati introdotti anche i componenti digitali, compreso il  software. Il software che svolge funzioni di sicurezza dovrà essere marcato CE ed essere accompagnato da una dichiarazione di conformità UE.

DICHIARAZIONE CONFORMITA' UE

La dichiarazione CE di conformità è stata sostituita da una dichiarazione di conformità UE, in linea con il nuovo quadro legislativo. Quando ad un prodotto si applicano più atti dell’UE, deve essere redatta un’unica dichiarazione di conformità UE che li racchiude tutti.

CYBERSECURITY

Altra importante novità: si prende atto che oggi le macchine (e sempre pù nei prossimi anni) sono sempre più interconnesse in rete, strutturate in sistemi potenzialmente molto complessi ed esposte ad attacchi del tutto analoghi a quelli che vengono effettuati contro le reti di computer. Sono già stati documentatti eventi di questo tipo e sono destinati ad aumentare in futuro.

Il nuovo Regolamento Macchine prescrive che i circuiti di comando che svolgono funzioni di sicurezza siano progettati in modo da evitare attacchi che possano causare comportamenti pericolosi delle macchine. 

La conseguenza logica di questa indicazione ci fa immaginare che in futuro avremo macchine protette da strati software specifici, come anti-virus, firewall, intrusion detectors o machine learning engine, del tutto simili a quelli che usiamo per proteggere le reti di computer.

Ovviamente questi aspetti avranno un impatto sul documento di valutazione dei rischi, che deve accompagnare la macchina.

STRESS PSICOLOGICO

Ambienti di lavoro robotizzati, in cui operatori umani condividono spazi di lavoro e processi con macchine robotizzate sempre più efficienti, possono generare dinamiche di stress per l'operatore umano. Tali elementi devono essere valutati per rispondere al requisito essenziale di sicurezza e di tutela della salute del lavoratore.

ALLEGATO IV della Direttiva diventa ALLEGATO I nel Regolamento

L’ALLEGATO IV della Direttiva, contenente la lista dei prodotti ad alto rischio, diviene ALLEGATO I del nuovo Regolamento. Ai prodotti compresi in questo allegato sono stati aggiunti i software e i sistemi di intelligenza artificiale che svolgono funzioni di sicurezza. Per questi prodotti, non è prevista la possibilità per il fabbricante di applicare la procedura di valutazione della conformità con controllo interno; quindi sarà sempre necessario l’intervento di un organismo "esterno".

ENTI NOTIFICATI

Gli Stati membri dovranno provvedere alla creazione e alla supervisione di enti notificati, incaricati dello svolgimento del risk-assessment sui macchinari e le loro funzionalità. Tali enti e le autorità che gestiscono le informazioni relative ai macchinari e ai soggetti produttori, importatori e distributori devono garantire la riservatezza dei dati contenuti nella documentazione che viene loro fornita.

Questo è uno degli aspetti più controversi del nuovo Regolamento Macchine.

Alcuni temono che l'attività di risk-assessment affidata ad una terza parte, per tutti i macchinari ad alto rischio, possa aumentare i costi di produzione e accrescere oneri amministrativi e tempi di commercializzazione.

Del resto, nell'esperienza professionale di molti miei colleghi che si occupano della documentazione tecnica delle macchine, ci sono innumerevoli episodi di macchine spesso carenti nella valutazione dei rischi o nella progettazione di base delle soluzioni di sicurezza.

La cronaca, anche recente, poi ci conferma come spesso le macchine vengano utilizzate rimuovendo i ripari di sicurezza o disattivando altri sistemi di sicurezza previsti, come nel caso della tragedia della funivia del Mottarone.

QUALI CONCLUSIONI POSSIAMO TRARRE?

Premesso che la bozza pubblicata potrebbe essere modificata e che i molti attori in campo non sono tutti concordi rispetto alle diverse modifiche introdotte rispetto alla vecchia Direttiva 2006/42/CE, non si può non cogliere il senso di una robusta e necessaria innovazione.

Se devo isolare solo 3 pti direi:

  • L'introduzione di una definizione di "macchina" che si apre alle nuove tecnologie (intelligenza artificiale, cyber security, etc.), che possono introdurre profili di rischio per la sicurezza dell'operatore che utilizza le macchine.
  • La presenza di un Ente "esterno" per le attività di risk-assessment di alcuni tipi di macchine o dei sistemi di macchine.
  • La possibilità di poter fornire la documentazione del prodotto in formato elettronico, come prima opzione.

Per come la vedo io, è un enorme balzo in avanti, rispetto ad una Direttiva ormai datata.

Ovviamente, il testo potrà essere migliorato e subire modifiche ed integrazioni fino al giorno della sua pubblicazione definitiva. Ma l'impianto generale, probabilmente, non sarà stravolto.

Per chi si occupa di Documentazine Tecnica (sarebbe meglio dire di "informazioni per l'uso" di un prodotto, come stabilito dallo standard 82079) si aprono nuove sfide: la documentazione in formato elettronico consente nuove possibilità, e l'integrazione della macchina con nuove tecnologie implica che il perimetro delle conoscenze da mettere in campo si allarga notevolemente.

Avremo modo di riprendere il tema. Per ora, è tutto.

Leggi questo articolo...

sabato 1 maggio 2021

Documentare le API: le aziende cercano l'Unicorno!

Ieri nella mia mail-box è arrivata questa offerta di lavoro (ho camuffato o tagliato informazioni che la rendessero troppo facilmente riconoscibile e i nomi di alcuni ben noti tools...):

Position

At XXXXXXXXXXXXXX, we create software that will enable our team to manage thousands of vehicles and customers on a daily basis. As an API technical writer, you play a key role in building our product by creating useful and engaging software documentation. You have the chance to join this team early on and...

Objectives

Best software to support business: Together with your team, you ship new features.... delivering the best software possible for our customers and business units

Strive for excellence: You strive to deliver the best possible experience for our users...

Providing beautiful software documentation: You help your engineering colleagues by writing high-quality and easy-to-understand documentation for the appropriate audiences

Your qualification

You have a Bachelor’s degree or equivalent. 3+ years creating API documentation in an agile development environment. Passion for creating useful and engaging software documentation with a strong customer-centric focus. Ability to work with API documentation tools such as..., or other docs-as-code approaches. Comfortable understanding codes in one or more programming languages, such as NodeJS or Python...JavaScript...

Experience in relevant product areas (e.g. eCommerce or B2C, SaaS platforms). Usability and testing skills with patience in problem-solving and troubleshooting. Talent in creating visual content using... Meticulous attention to detail and joy in precise working. You have a “never-stop-learning” attitude and a desire to develop and grow. You are fluent in English.

In un precedente articolo vi avevo indicato quali dovessero essere le migliori caratteristiche di un API Technical Writer.

Se rileggete l'articolo e lo confrontate con l'annuncio, vi accorgerete che non vi ho mentito!

Aldilà delle battute, la "API economy" richiede una figura professionale NUOVA o forse potremmo dire una "SPECIALIZZAZIONE" nel campo della Comunicazione Tecnica. I fondamentali classici del technical writing hanno ancora un ruolo ovviamente, ma sono solo LA BASE su cui costruire un nuovo asset di competenze.

Se avete fatto caso, questo annuncio di lavoro è rivolto ad un profilo sostanzialmente junior, che però si è già "infarinato le mani" in questo ruolo. In realtà, non esiste "una scuola" per diventare API Techcnical Writer. 

In Italia non esiste nemmeno un percorso degno di questo nome per imparare le basi del technical writing, ma questa è un'altra conversazione.



In altri termini, le aziende hanno bisogno di Unicorni... che come ben sapete, non si trovano facilmente!

Io mi sono occupato per la prima volta di documentare delle API nel 2005, ma io non faccio giursiprudenza, perchè parto in vantaggio: sono un Ing. Informatico che poi è diventato un Tech Writer.
Tanto per avere un'idea, io sono allineato con tutte le caratteristiche dell'annuncio... tranne le gioventù!

Presto inizierò un nuovo ciclo di articoli sulla API economy e su come si documentano le API.
A presto.

Leggi questo articolo...

lunedì 5 aprile 2021

Una conversazione sulla documentazione del software con Ferry Vermeulen e Sissi Closs

Recentemente ho avuto l'onore ed il piacere di essere intervistato, insieme a Sissi Closs, da Ferry Vermeulen. L'intervista è stata registrata in un podcast di circa 90 minuti che potete ascoltare (e scaricare) da questo link.

Non voglio anticiparvi i dettagli di questa conversazione, dove emergono tutte le questioni principali che vanno indirizzate nella definizione delle migliori strategie per la documentazione del software.

Abbiamo parlato di Minimalismo, processi Agile, SaaS, documentazione Task Oriented, riuso dei contenuti, standard ISO (in particolare dello standard 26514 ed 82079), standard tecnici e linguistici, CCMS e altro ancora.

In 90 minuti abbiamo provato ad inquadrare un argomento estremamente complesso e spero che possiate trarne indicazioni utili, in special modo se state iniziando ad orientarvi sul tema.

Ferry è già noto ai lettori di questo blog, perché in passato ho commentato alcuni suoi straordinari articoli, tra cui:

Definizione della Dichiarazione di Conformità

Intervista sul Minimalismo al Prof. Van der Meij

Ferry Vermeulen è il Direttore Tecnico di INSTRKTIV; il blog di INSTRKTIV è tra i migliori blog al mondo per quanto riguarda le tematiche sulla Comunicazione Tecnica.

Ferry è anche membro, come me, dell'Advisory Board for Legislation and Standard (ABLS) della Tekom Europe.

Anche la Prof.ssa Sissi Closs fa parte dell'ABLS, ed è da molti anni un punto di riferimento per i suoi studenti e per tutti i professionisti del nostro settore.

Con Sissi (e con Andrea Gocke) abbiamo anche scritto un articolo "a 6 mani" sullo standard ISO/IEC/IEEE 26515.

Che dire di più? Scaricate il podcast e buon ascolto!

Leggi questo articolo...

mercoledì 25 novembre 2020

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

lunedì 16 novembre 2020

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

giovedì 29 ottobre 2020

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

lunedì 26 ottobre 2020

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

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