10 extra per un’ottima documentazione di API

Pagina della panoramica generale#section1

Chiunque visiti la documentazione della vostra API deve essere in grado di decidere al primo sguardo se valga la pena esplorare oltre. Dovreste mostrare chiaramente:

• cosa offre la vostra API (ossia, cosa fanno i vostri prodotti),
• come funziona,
• come si integra,
• come scalarla (ossia, limiti di utilizzo, prezzi, supporto e Service Level Agreements).

La API documentation di Spotify dichiara chiaramente cosa fa la API e come funziona e fornisce dei link a guide e API references organizzati in categorie.

Una pagina di panoramica generale è indirizzata a tutti i visitatori, ma può essere particolarmente utile per i decision-maker. Devono vedere il valore del business: spiegategli direttamente perché un’azienda dovrebbe usare la vostra API.

D’altro canto, gli sviluppatori vogliono comprendere lo scopo della API e il suo insieme di feature, quindi tendono a guardare alla pagina della panoramica per delle informazioni concettuali. Mostrate loro l’architettura della vostra API e la struttura dei vostri documenti. Includete una panoramica di diversi componenti e un’introduzione al comportamento request-response (ossia, come integrare, come mandare le richieste e come processare le risposte). Fornite informazioni sulle piattaforme su cui gira la API (es., Java) e le possibili interazioni con altre piattaforme.

Come ha scoperto lo studio “The role of conceptual knowledge in API usability”, senza una conoscenza concettuale, gli sviluppatori hanno delle difficoltà nel formulare delle domande efficaci e nel valutare la rilevanza o il significato del contenuto che hanno trovato. Questo è il motivo per cui la documentazione della API dovrebbe non solo includere esempi dettagliati sull’uso della API, ma anche introduzioni accurate ai concetti, agli standard e alle idee nelle strutture dati e sulla funzionalità di un’API. La pagina della panoramica può essere una componente importante per adempiere a questo ruolo.

La pagina della overview di Braintree fornisce una chiara panoramica del loro SDK, insieme a una spiegazione passo-passo visuale di come funziona la loro API.

Esempi#section2

Per alcuni sviluppatori, gli esempi giocano un ruolo molto importante nel familiarizzare con una API rispetto alle spiegazioni di call e parametri.

Uno studio recente, “Application Programming Interface Documentation—What Do Software Developers Want?”, ha esplorato il modo in cui interagiscono gli sviluppatori software con la documentazione di un’API: quali sono i loro obiettivi, in che modo apprendono, dove cercano informazioni e come giudicano la qualità dei documenti della API.

Il ruolo degli esempi#section3

Lo studio ha scoperto che dopo aver condotto una panoramica iniziale di quello che fa e come funziona l’API, i developer affrontano l’apprendimento della API in due modi distinti: alcuni seguono un approccio top-down, in cui cercano di costruire una comprensione completa della API prima di cominciare a implementare degli specifici use case, mentre altri preferiscono seguire un approccio bottom-up, in cui cominciano subito a scrivere codice.

Questo ultimo gruppo ha una strategia di apprendimento code-oriented: cominciano a imparare cercando ed estendendo degli esempi di codice. Immergersi in un’API nella maggior parte dei casi è collegato a un task specifico. Cercano un esempio che abbia il potenziale di servire come base per risolvere il loro problema, ma una volta che hanno trovato la soluzione che cercavano, di solito smettono di imparare.

Gli esempi sono essenziali per i principianti code-oriented, ma tutti gli sviluppatori ne traggono beneficio. Lo studio ha mostrato che spesso i developer si fidano più degli esempi che della documentazione perché, se funzionano, non possono essere datati o sbagliati. Spesso gli sviluppatori lottano per trovare da dove cominciare e in che modo cominciare con una nuova API: in questo caso, gli esempi possono diventare un ottimo punto d’ingresso. Molti sviluppatori possono afferrare le informazioni più facilmente dal codice che dal testo e possono riutilizzare il codice negli esempi per le loro implementazioni. Gli esempi giocano anche altri ruoli che sono ben lontani dall’ovvio: forniscono automaticamente delle informazioni su dipendenze e prerequisiti, aiutano ad identificare le sezioni rilevanti nella documentazione quando gli sviluppatori scorrono la pagina e mostrano agli sviluppatori in maniera intuitiva in che modo dovrebbe apparire il codice che usa l’API.

Migliorate i vostri esempi#section4

Dal momento che gli esempi sono dei componenti così cruciali nella documentazione della API, esempi migliori implicano documenti migliori.

Per assicurare la qualità dei vostri esempi, essi dovrebbero essere completi, programmati professionalmente e funzionare in maniera corretta. Dal momento che gli esempi convogliano molto di più del solo use case in considerazione, assicuratevi di seguire le linee guida di stile delle rispettive community e mostrate gli approcci best practice. In breve, spiegazioni informative: sebbene gli esempi possano essere auto-spieganti, i commenti inclusi negli esempi di codice aiutano la comprensione.

Aggiungete degli esempi concreti, reali, ogni volta che potete. Se non avete degli esempi reali, assicuratevi che almeno appaiano tali: usate dei nomi di variabile e funzioni realistici invece di nomi astratti.

Quando includete degli esempi, avete una varietà di formati e approcci tra cui scegliere: esempi auto-generati, applicazioni tipo, client libraries ed esempi in più linguaggi.

Esempi auto-generati#section5

I tool di auto-documentazione come Swagger Codegen e API Blueprint generano automaticamente la documentazione dal vostro codice sorgente e la mantengono aggiornata man mano che il codice cambia. Usateli per generare delle librerie di riferimento e delle snippet di codice tipo, ma siate coscienti che quello che producete in questo modo è solo un’ossatura, non una documentazione completa. Dovrete ancora aggiungere le spiegazioni, le informazioni concettuali, le guide quick-start e i tutorial e dovrete ancora prestare attenzione ad altri aspetti come la UX e il copy di buona qualità.

Sul blog Readme, si esplorano i tool di auto-doc e i loro limiti in maggiore dettaglio attraverso un paio di esempi tratti dal mondo reale.

Applicazioni campione#section6

Le applicazioni funzionanti che usano la API sono un ottimo modo per mostrare come tutto funzioni nel suo insieme e in che modo l’API si integri con diverse piattaforme e tecnologie. Sono diverse dalle snippet di codice di esempio, perché sono soluzioni stand-alone che mostrano il quadro generale. Come tali, sono utili agli sviluppatori che vorrebbero vedere in che modo funziona un’implementazione completa e avere una comprensione generale del modo in cui tutto si lega nella API. D’altro canto, sono dei prodotti reali che mostrano i servizi e la qualità della vostra API ai decision makers. L’iOS Developer Portal di Apple offre degli esempi sorgenti buildable ed eseguibili di come portare a termine un task usando una tecnologia particolare in un’ampia varietà di categorie.

Client libraries#section7

Le client libraries sono pezzi di codice che gli sviluppatori possono aggiungere ai propri progetti di sviluppo. Solitamente sono disponibili in vari linguaggi di programmazione e coprono le funzionalità base di un’applicazione per essere in grado di interagire con la API. Fornirli è una feature extra che richiede un investimento continuo da parte del provider dell’API, ma farle aiuta i developer a partire di slancio con l’uso della API. GitHub segue l’approccio pratico di offrire client libraries per i linguaggi che sono più comunemente usati con la loro API, mentre mettono dei link a librerie non supportate, create dalla community, scritte in altri linguaggi meno popolari.

Esempi in più linguaggi#section8

Per loro natura, le API sono indipendenti dalla piattaforma e dal linguaggio. Gli sviluppatori possono usare i servizi di un’API con il linguaggio di loro scelta, ma questo significa che una buona documentazione dovrebbe coprire almeno i linguaggi più popolari usati con quella particolare API (e.g., C#, Java, JavaScript, Go, Objective-C, PHP, Python, Ruby e Swift). Non solo dovreste fornire del codice di esempio e delle applicazioni di esempio in diversi linguaggi, ma questi esempi dovrebbero anche riflettere l’approccio best-practice per ogni linguaggio.

Usabilità#section9

La documentazione dell’API è uno strumento che aiuta sviluppatori e altri stakeholder a fare il proprio lavoro. Dovreste adattarla al modo in cui le persone la usano e renderla il più semplice da usare possibile. Considerate i seguenti fattori:

• Copy and paste: Gli sviluppatori fanno copia e incolla degli esempi di codice per usarli come punto di partenza per le loro implementazioni. Rendete più semplice questo processo o con un pulsante “copy” vicino alle sezioni importanti o rendendo semplice evidenziare e copiare le sezioni.
• Sticky navigation: Se ben implementato, fissare l’indice o un’altra navigazione nella visualizzazione della pagina può far sì che gli utenti non si perdano e abbiano controllo quando ritornano verso l’alto.
• Click: Minimizzate i click tenendo vicini gli uni agli altri gli argomenti correlati.
• Selettore del linguaggio: I developer dovrebbero essere in grado di vedere gli esempi nel linguaggio che hanno scelto. Mettete un selettore del linguaggio sopra alla sezione degli esempi di codice e assicuratevi che la pagina ricordi il linguaggio selezionato dall’utente.
• URL: Le viste singola pagina possono risultare in pagine molto lunghe, quindi assicuratevi che le persone possano mettere dei link a certe sezioni della pagina. Se, tuttavia, una visualizzazione a pagina singola non funziona per i vostri doc, non agitatevi: semplicemente, separate le diverse sezioni su pagine separate.
  

  Grande usabilità: La documentazione della API di Stripe cambia l’URL dinamicamente man mano che si scorre lungo la pagina.

  Altra best practice da Stripe: anche il selettore del linguaggio cambia l’URL, così che gli URL portino nella giusta posizione nel giusto linguaggio.

• Collaborazione: Considerate di permettere agli utenti di contribuire ai vostri doc. Se vedete che i vostri utenti fanno delle modifiche alla vostra documentazione, indica che ci potrebbe essere spazio per un miglioramento, in quelle parti della vostra documentazione o addirittura nel vostro codice. Inoltre, i vostri utenti vedranno che le questioni sono gestite e la documentazione viene aggiornata frequentemente. Un modo per facilitare la collaborazione è quello di avere la documentazione su GitHub, ma tenete presente che questo limiterà le vostre opzioni di interattività, dal momento che GitHub ospita file statici.

Interattività#section10

Fornire un’opzione per gli utenti per interagire con la vostra API attraverso la documentazione migliorerà moltissimo l’esperienza dello sviluppatore e darà un’accelerata all’apprendimento.

Per prima cosa, fornite una API key funzionante per fare dei test, o, ancora meglio, permettete agli utenti di fare il login sul sito della vostra documentazione e fate inserire loro la loro API key in dei comandi e in del codice di esempio. In questo modo possono copiare, incollare e far girare subito il codice.

Come passo seguente, permettete ai vostri utenti di fare delle API call direttamente dal sito stesso. Per esempio, fategli fare delle query a un database di esempio, fategli modificare le loro query e vedere i risultati di questi cambiamenti.

Un modo più sofisticato per rendere più interattiva la vostra documentazione è quello di fornire una sandbox: un ambiente controllato in cui gli utenti possono testare call e funzioni con risorse note, manipolando dati in tempo reale. Gli sviluppatori imparano attraverso l’esperienza ad interagire con la vostra API nella sandbox, piuttosto che passando dalla lettura della documentazione a provare loro stessi gli esempi di codice. Nordic APIs spiega il vantaggio del sandboxing, discute il ruolo della documentazione in un ambiente sandboxed e mostra una possibile implementazione. Per vedere una sandbox in azione, provate quella sul developer site di Dwolla.

Aiuto#section11

Lo studio che esplorava il modo in cui i software developer interagiscono con la API documentation ha anche esplorato il modo in cui i developer cercano aiuto. In un ambiente di lavoro naturale, solitamente, chiedono prima ai propri colleghi. Poi, comunque, molti di loro tendono a cercare sul web delle risposte invece di consultare la documentazione ufficiale del prodotto. Questo significa che dovreste essere sicuri che la vostra documentazione della API sia ottimizzata per i motori di ricerca e che ritorni dei risultati rilevanti nelle query di ricerca.

Per essere sicuri di avere i contenuti necessari disponibili per l’auto-aiuto, includete le FAQ e una knowledge base ben organizzata. Per un aiuto rapido e per un’interazione umana, fornite una form di contatto e, se ne avete la possibilità, una soluzione help desk direttamente dai vostri doc, per esempio, una live chat con uno staff di supporto.

Tale studio ha anche evidenziato il ruolo significativo giocato da Stack Overflow: la maggior parte degli sviluppatori intervistati ha citato il sito come fonte affidabile di auto-aiuto. Potete anche supportare il lavoro di auto-aiuto dei vostri sviluppatori e il senso di community aggiungendo un vostro developer forum al vostro developer portal o fornendo un canale IRC o Slack.

Changelog#section12

Come con tutto il software, le API cambiano e vengono regolarmente aggiornate con nuove feature, bug fix e miglioramenti della performance.

Quando esce una nuova versione della vostra API, dovete informare dei cambiamenti gli sviluppatori che ci lavorano così che possano reagirvi di conseguenza. Un changelog, chiamato anche “note di rilascio”, include le informazioni riguardanti le versioni attuali e quelle precedenti, solitamente ordinate per data e per numero di versione, insieme ai cambi associati.

Se ci sono dei cambiamenti in una nuova versione che possono rompere l’utilizzo di una vecchia versione dell’API, mettete dei warning in cima ai changelog rilevanti, addirittura in cima alla vostra pagina delle note di rilascio. Potete anche portare attenzione a questi cambiamenti sottolineandoli o evidenziandoli in maniera permanente.

Per tener aggiornati gli sviluppatori, offrite un feed RSS o la sottoscrizione a una newsletter, in cui possano essere notificati gli aggiornamenti alla vostra API.

Oltre all’aspetto pratico, un changelog serve anche come segnale di fiducia che la API e la sua documentazione sono attivamente mantenuti e che le informazioni incluse sono aggiornate.

Statistiche e feedback#section13

Potete fare un po’ di ricerca conoscendo i vostri attuali clienti e quelli potenziali, parlando con le persone alle conferenze, esplorando i vostri competitor e perfino facendo dei questionari. Ciononostante, dovrete fare ancora molte supposizioni quando costruirete per la prima volta la documentazione della API.

Comunque, una volta che i documenti saranno caricati, potrete cominciare a raccogliere dei dati sul loro utilizzo e del feedback per capire come poterli migliorare.

Scoprite attraverso le statistiche quali sono i casi d’uso più popolari. Osservate quali endpoint vengono usati maggiormente e assicuratevi di dare loro la priorità quando lavorerete sulla documentazione. Prendete spunto per dei tutorial e osservate quali casi d’uso non avete ancora coperto con un walkthrough step-by-step da siti di community di sviluppatori come Stack Overflow o i vostri forum per sviluppatori. Se una domanda che riguarda la vostra API salta fuori in questi canali e vedete delle persone che discutono dell’argomento attivamente, dovreste controllare se è qualcosa che dovete spiegare nella documentazione.

Raccogliete le informazioni dal vostro team di supporto. Quando vengono contattati dagli utenti? Ci sono delle domande ricorrenti a cui non riescono a trovare risposta nella vostra documentazione? Migliorate la documentazione in base al feedback da parte del team di supporto e verificate se avete avuto successo: gli utenti hanno smesso di fare le domande a cui avete risposto?

Ascoltate il feedback e valutate come potete migliorare la vostra documentazione basandovi su di esso. Il feedback può arrivare da molti canali diversi: workshop, training, blog post e commenti riguardanti la vostra API, conferenze, interviste con i clienti o studi di usabilità.

Leggibilità#section14

La leggibilità è la misura di quanto facilmente un testo scritto possa essere compreso da un lettore: include fattori visuali come l’aspetto dei font, i colori e il contrasto, e fattori contestuali come la lunghezza delle frasi, la scelta delle parole e il gergo. Si consulta la documentazione per imparare qualcosa di nuovo o per risolvere un problema. Non rendetegli il processo più difficile con del testo difficile da comprendere.

Mentre in generale dovreste avere come obiettivo la chiarezza e la brevità fin dal principio, ci sono alcuni aspetti specifici su cui potete lavorare per migliorare la leggibilità della documentazione dell’API.

Audience: aspettatevi che non tutti i vostri utenti saranno sviluppatori e che anche gli sviluppatori avranno delle skill e delle conoscenze pregresse sulla vostra API e sul business domain molto differenti. Per soddisfare i vari bisogni dei vari gruppi nel vostro pubblico target, spiegate tutto nei dettagli, ma fornite dei modi per chi ha già familiarità con la funzionalità di trovare rapidamente quello che stanno cercando, per esempio, aggiungete una quick reference organizzata in maniera logica.

Formulazione: spiegate tutto il più semplicemente possibile. Usate frasi brevi e assicuratevi di essere consistenti con etichette, nomi nel menu e altro contenuto testuale. Includete una spiegazione chiara e diretta per ogni call. Evitate il gergo se possibile e, se non si può, mettete dei link alle definizioni relative al dominio la prima volta che lo usate. In questo modo sarete sicuri che le persone che non hanno familiarità con il vostro business domain possano ottenere l’aiuto di cui necessitano per comprendere la vostra API.

Font: sia la dimensione del font sia il tipo di font influenzano la leggibilità. Usate titoli brevi per le sezioni e usate il title case per rendere più semplice scorrerli. Per il testo più lungo, usate i font sans serif. Nella stampa, i font serif rendono più semplice la lettura, ma online, i caratteri serif possono confondersi. Optate per font come Arial, Helvetica, Trebuchet, Lucida Sans, o Verdana, che è stato disegnato apposta per il Web. Anche il contrasto gioca un ruolo importante: più alto il contrasto, più facile da leggere sarà il testo. Prendete in considerazione l’uso di un font di dimensione leggermente più grande e caratteri diversi per il codice e il testo per aiutare gli utenti a orientarsi con la vista quando vanno avanti e indietro tra il loro editor di codice e la vostra documentazione.

Struttura: la documentazione della API dovrebbe soddisfare i bisogni sia dei nuovi visitatori che di quelli che ritornano (es., gli sviluppatori che fanno il debug la loro implementazione). Una struttura logica che sia semplice da navigare e che permetta una quick reference funziona per entrambe. Dotatevi di un indice chiaro e di una lista organizzata di risorse e create sezioni, sottosezioni, error case e display state direttamente collegabili.

Grande usabilità: linkabilità dimostrata nella documentazione della API di Stripe.

Scorrevolezza: come sostiene Steve Krug nel suo libro sull’usabilità web, Don’t Make Me Think, uno dei fatti più importanti è che gli utenti web non leggono, scorrono. Per rendere più semplice la scansione del testo, usate paragrafi brevi, sottolineate le parole importanti e usate liste ogni volta che potete.

Accessibilità: sforzatevi di rendere la vostra documentazione API accessibile a tutti gli utenti, inclusi gli utenti che accedono alla vostra documentazione tramite tecnologia assistiva (es., screen reader). Siate coscienti del fatto che gli screen reader potrebbero spesso avere dei problemi nella lettura del codice e potrebbero gestire la navigazione in maniera diversa, quindi esplorate come leggono il contenuto gli screen reader. Imparate di più sull’accessibilità web, studiate le Web Content Accessibility Guidelines e fate del vostro meglio per aderirvi.

Personalità#section15

Avete lavorato sodo per cercare di conoscere il vostro pubblico e seguire le best practice per lasciare una buona impressione con la vostra documentazione della API. Ora, come tocco finale, potete assicurarvi che i vostri doc “suonino” e appaiano in sintonia con il vostro brand.

Sebbene la documentazione di una API e i testi tecnici in generale non lascino molto spazio per gli esperimenti di tono e stile, potete ancora instillare della personalità nei vostri doc:

• Usate il vostro brand book e assicuratevi che i vostri API doc lo seguano alla lettera.
• Un tono amichevole e uno stile semplice possono fare meraviglie. Ricordate, le persone sono qui per studiare la vostra API e risolvere un problema. Aiutateli parlandogli in maniera naturale e facile da capire.
• Aggiungete delle illustrazioni che aiutino i vostri lettori a comprendere ogni parte della API. Mostrate la relazione fra le varie parti, visualizzate i concetti e i processi.
• Selezionate attentamente i vostri esempi così che riflettano il vostro prodotto nel modo in cui volete. Implementazioni giocose della vostra API creeranno un’impressione diversa rispetto agli use case più seri o aziendali. Se il vostro brand lo permette, potete anche aggiungere un po’ di divertimento con degli esempi (es., esempi e nomi di variabile divertenti), ma non esagerate.
• Potete inserire alcune immagini (oltre alle illustrazioni) dove possibile, ma assicuratevi che aggiungano qualcosa ai vostri documenti e che non distraggano il lettore.

Pensate al developer portal e oltre#section16

Sebbene si stia ancora discutendo su dove tracciare la linea di confine tra la documentazione API e il developer portal, la maggior parte delle persone che lavorano nella comunicazione tecnica sembra essere d’accordo che un developer portal è un’estensione della documentazione della API. In origine, la documentazione della API significava strettamente solo documenti di riferimento, ma poi sono entrati a far parte del pacchetto anche gli esempi, i tutorial e le guide per cominciare. Tuttavia, li chiamiamo ancora API doc. Al crescere del mercato per la developer communication, i fornitori si sforzano di estendere la developer experience oltre la documentazione della API a un developer portal a pieno titolo.

In effetti, alcune delle idee discusse prima, come un developer forum o delle sandbox, puntano già nella direzione della creazione di un developer portal. Un developer portal è il passo successivo nella developer communication, dove oltre a dare ai developer tutto il supporto di cui necessitano, si comincia a costruire una community. I developer portal possono includere il supporto oltre i doc, come un blog o dei video. Se rientra nel business model, possono anche contenere un app store dove i developer inviano le loro implementazioni e lo store fornisce loro un framework per gestire l’intero processo di vendita. I portali connessi a un’API spesso contengono anche un’area separata con delle landing page e mostrano dove potete parlare direttamente ad altri stakeholder, quali vendite e marketing.

Anche se avete già iniziato a costruire il vostro developer portal, potete ancora trovare dei modi per imparare di più ed estendere la vostra portata. Partecipate e presentate a conferenze quali DevRelCon, Write The Docs o API The Docs per essere coinvolti nelle developer relation. Usate i social media: twittate, unitevi a gruppi di discussione o create una newsletter. Esplorate l’annuale Stack Overflow Developer Survey per saperne di più sul vostro pubblico target principale. Organizzate dei code and documentation sprint, dei training e dei workshop. Zapier ha un’ottima collezione di blog e altre risorse che potete seguire per stare aggiornati con l’economia in continuo cambiamento delle API: vi troverete sicuramente anche le vostre fonti di ispirazione.

Spero che “I dieci fondamenti di un’ottima documentazione di API” e questo articolo vi abbiano dato delle informazioni di valore per la creazione e il miglioramento della documentazione della vostra API e vi ispirino a cominciare o a proseguire.