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?
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:
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.
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:
- Quelli che... "chi scrive la documentazione del prodotto deve essere un esperto del prodotto..."
- Quelli che... "un Comunicatore Tecnico può scrivere la documentazione di qualsiasi prodotto... anzi meno è esperto di una certa tecnologia e meglio è..."
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.
A presto.
Nessun commento:
Posta un commento