Titolo originale: The Ten Essentials for Good API Documentation

Pubblicato in:

Scritto da Diána Lakatos

La documentazione di una API è il primissimo riferimento per chiunque implementi la vostra API e può influenzare profondamente l'esperienza dello sviluppatore. Dal momento che descrive quali servizi offre una application programming interface e come usarli, la documentazione creerà inevitabilmente un'impressione sul prodotto, nel bene e nel male.

In questa serie in due parti condividerò con voi quello che ho imparato sulla documentazione di API. Questa parte discute i fondamenti per aiutarvi a creare dei buoni documenti della API, mentre nella parte due, “Ten Extras for Great API Documentation”, vi mostrerò dei modi aggiuntivi per migliorare e rifinire la vostra documentazione.

Conoscere il proprio pubblico

Sapere a chi vi rivolgete con i vostri scritti e come poter offrire loro il miglior supporto vi aiuterà a prendere delle decisioni riguardanti il design, la struttura e il linguaggio dei vostri documenti. Dovrete sapere chi visita la documentazione della vostra API e per cosa vogliono usarla.

La documentazione della API verrà probabilmente visitata e usata dai seguenti audience.

Developer

Basandosi sulle loro capacità, esperienze e ruoli nei progetti, gli sviluppatori saranno generalmente il gruppo più grande e più variegato. Useranno i vostri documenti in modi diversi.

In Pronovix, abbiamo cominciato a fare dei workshop sui portali per developer con i nostri clienti per aiutarli a imparare di più su cosa hanno bisogno i developer e in che modo supportare meglio il loro lavoro e quello che cercano davvero in una documentazione di API. Tutto ciò è inoltre supportato da una robusta ricerca, come i risultati pubblicati nell'articolo di Stephanie Steinhardt provenienti da un programma di ricerca di due anni presso la Merseburg University of Applied Sciences.

Principianti: gli sviluppatori a cui manca una precedente esperienza con la vostra API tendono ad aver bisogno di maggior supporto. Sfrutteranno le guide “quick start” che li incoraggiano a cominciare ad usare la vostra API: tutorial chiari, concisi, passo-passo per gli argomenti più importanti e campioni di codice ed esempi che li aiutino a capire come usarla in progetti reali. Se renderete piacevole l'onboarding per i principianti, sarà molto più probabile che si impegneranno a imparare ogni sfumatura della vostra API.

Sviluppatori esterni: gli sviluppatori che lavorano già con la vostra API torneranno ripetutamente alla documentazione e la useranno come materiale di riferimento. Avranno bisogno di informazioni rapide su tutte le funzionalità offerte dalla vostra API, strutturate in una maniera semplice da capire per aiutarli a trovare rapidamente ciò di cui hanno bisogno.

Debugger: i developer che usano la vostra API incontreranno degli errori di tanto in tanto e useranno la vostra documentazione per analizzare le risposte e gli errori che saltano fuori.

Sviluppatori interni: gli API provider tendono a concentrarsi così tanto sul loro pubblico esterno che si dimenticano dei propri sviluppatori. Anche i team interni che lavorano sulla API useranno la documentazione dell'API.

Questi sono solo alcuni degli use case più comuni.

Decision maker

I decision maker come i CTO e i product manager controlleranno anche loro la vostra documentazione e valuteranno la vostra API. Devono determinare se la vostra API va bene per il loro progetto oppure no, quindi è cruciale per il vostro business che questo gruppo possa trovare facilmente e rapidamente quello che sta cercando.

Altri audience

Sebbene non così comune, anche i giornalisti, gli autori tecnici, lo staff di supporto, i developer evangelist e addirittura i vostri competitor potrebbero leggere la vostra documentazione della API.

Ricordatevi lo scopo della documentazione

La base della vostra documentazione della API è una spiegazione chiara di ogni call e di ogni parametro.

Come minimo sindacale, dovreste descrivere in dettaglio:

  • cosa fa ogni chiamata nella vostra API
  • ogni parametro e tutti i suoi possibili valori, inclusi il loro tipo, la formattazione, le regole e se è “required” oppure no.

Struttura basata sul contesto

Nessuno leggerà la vostra documentazione dell'API in ordine e non potete prevedere dove atterreranno. Questo significa, che dovete fornire tutte le informazioni necessarie nel contesto. Quindi, seguendo le “best practice” della scrittura per argomento, dovreste includere tutte le informazioni necessarie e correlate nella spiegazione di ogni chiamata.

Context.IO, per esempio, ha fatto un'ottimo lavoro nel documentare ognuna delle loro chiamate API separatamente con informazioni dettagliate sui parametri e sui loro possibili valori, insieme a suggerimenti utili e link ad argomenti correlati.

Esempi

Per essere in grado di implementare la vostra API, gli sviluppatori devono capirla insieme al dominio a cui fa riferimento (per es., l'e-commerce). Gli esempi tratti dal mondo reale riducono il tempo necessario per familiarizzare con il vostro prodotto e allo stesso tempo forniscono della conoscenza di dominio.

Aggiungete quello che segue alla descrizione di ogni call:

  • un esempio di come vada fatta la call
  • una spiegazione della request
  • delle risposte di esempio

Alcuni studi hanno dimostrato che ad alcuni developer piace immergersi immediatamente nel codice e quando devono imparare una nuova API cominciano a lavorare partendo da un esempio. L'analisi dei record di eye tracking hanno mostrato che gli elementi visuali, come il codice di esempio, catturano l'attenzione degli sviluppatori che scorrono lungo la pagina, piuttosto che leggerla riga per riga. Molti hanno cercato il codice di esempio prima di cominciare a leggerne le descrizioni.

Usare gli esempi giusti è un modo sicuro per migliorare la documentazione dell'API. Esplorerò dei modi per rendere ottima della documentazione API già buona usando degli esempi nel mio prossimo post “Ten Extras for Great API Documentation”.

Messaggi d'errore

Quando qualcosa non va per il verso giusto durante lo sviluppo, sistemare il problema senza della documentazione dettagliata può diventare un processo frustrante e che richiede molto tempo. Per rendere questo processo il più liscio possibile, i messaggi d'errore dovrebbero aiutare gli sviluppatori a capire:

  • quale sia il problema,
  • se l'errore è stato generato dal loro codice o dall'uso dell'API
  • e come sistemare il problema.

Tutti i possibili errori, inclusi i casi limite, dovrebbero essere documentati nei messaggi di errore con dei codici di errore o con delle brevi informazioni comprensibili dalle persone. I messaggi d'errore non dovrebbero contenere solo le informazioni relative a quella specifica call, ma anche coprire degli argomenti universali come l'autenticazione o le HTTP request e altre condizioni non controllate dalla API (come request timeout or unknown server error).

Questo post da Box discute le best practice per la gestione e la comunicazione di errori server-side, come il ritornare un HTTP status code che sia molto simile all'erro condition, messaggi d'errore comprensibili dagli umani e codici d'errore machine-readable.

Guida quickstart

I principianti che cominciano a implementare la vostra API si trovano di fronte molti ostacoli:

  • Sono all'inizio di una curva di apprendimento molto ripida
  • Potrebbero non avere familiarità con la struttura, il dominio e le idee che stanno dietro alla vostra API
  • È difficile per loro capire da dove partire.

Se non rendete semplice il processo di apprendimento per loro, possono sentirsi sopraffatti e si tratterranno dall'approfondire la vostra API.

Molti developer imparano facendo, quindi un'ottima opzione è una guida quickstart. La guida dovrebbe essere breve e semplice, indirizzata ai principianti e dovrebbe elencare il numero minimo di step richiesti per completare un task significativo (per es., scaricare la SDK e salvare un oggetto nella piattaforma). Le guide quickstart solitamente devono includere delle informazioni sul dominio ed introdurre in maggior dettaglio delle espressioni e dei metodi relativi al dominio. È meglio presumere che lo sviluppatore non abbia mai sentito prima del vostro servizio.

Le guide quickstart di Stripe e Braintree sono degli ottimi esempi: entrambe forniscono una panoramica dei task più probabili che vorrete realizzare mediante l'API, così come dei link ad informazioni rilevanti. Contengono inoltre dei link per contattare qualcuno in caso di bisogno.

Tutorial

I tutorial sono delle guide dettagliate step by step che coprono funzionalità specifiche che gli sviluppatori possono implementare con la vostra API, come le notifiche SMS, la verifica dell'account, etc.

I tutorial per le API dovrebbero seguire le best practice per scrivere un qualunque tipo di aiuto step by step. Ogni step dovrebbe contenere tutte le informazioni necessarie a quel punto e nulla di più. In questo modo, gli utenti possono concentrarsi sul task corrente e non saranno sommersi di informazioni di cui non hanno bisogno.

La descrizione degli step dovrebbe essere facile da seguire e concisa. La chiarezza e la brevità supportano il processo di apprendimento e sono una “best practice” per tutti i tipi di documentazione. Evitate il gergo, se possibile: gli utenti stanno imparando il linguaggio relativo al dominio e una nuova tecnologia, per cui il gergo può creare confusione. Aiutateli rendendo tutte le descrizioni quanto più possibile semplici da capire.

La guida dettagliata (o walkthrough) dovrebbe essere il pezzo più piccolo possibile che permetta agli utenti di portare a termine un task. Se un processo è troppo complesso, pensate a suddividerlo in pezzi più piccoli. Questo assicura che gli utenti possano avere l'aiuto di cui hanno bisogno senza passare per step a cui non sono interessati.

Screenshot della pagina del tutorial di Twilio

I tutorial di Twilio spiegano gli use case più probabili con delle app di esempio in un'ampia varietà di linguaggi di programmazione e framework.

Argomenti universali

Per implementare la vostra API, ci sono alcuni argomenti più ampi che gli sviluppatori dovranno conoscere, per esempio:

  • autenticazione. Gestita in maniera diversa da ogni tipo di API, l'autenticazione (per es., OAuth) è spesso un processo complicato e propenso all'errore. Spiegate in che modo ottenere le credenziali, come vengono passate al server e mostrate come funzionano le API key con il codice d'esempio.
  • Gestione degli errori. Per ora, la gestione degli errori non è ancora stata standardizzata, quindi dovreste aiutare i developer a capire come la vostra API ritorna informazioni d'errore, perché si verifica un errore e in che modo sistemarlo.
  • HTTP requests. Potreste anche dover documentare delle informazioni relative a HTTP, come i content types, gli status codes e il caching.

Dedicate una sezione separata a spiegare questi argomenti e collegate questa sezione da ogni API call pertinente. In questo modo potete essere sicuri che gli sviluppatori vedranno chiaramente in che modo la vostra API gestisce questi argomenti e in che modo le API calls cambiano il comportamento basandosi su queste.

Layout e navigazione

Il layout e la navigazione sono essenziali per la user experience e, sebbene non ci sia una soluzione universale per tutti i documenti API, ci sono alcune best practice che aiutano gli utenti a interagire con il materiale.

Layout dinamico

La maggior parte dei buoni esempi di documentazione di API usano un layout dinamico perché rende più semplice la navigazione per gli utenti rispetto a dei layout statici quando si cercano dei topic specifici in una documentazione vasta. Cominciare con un layout dinamico e scalabile, inoltre, vi assicurerà di poter espandere facilmente la vostra documentazione al bisogno.

Design single page

Se la documentazione della vostra API non è enorme, scegliete un design single page che permette agli utenti di farsi un'idea della struttura generale a colpo d'occhio. Introducete i dettagli da lì. I lunghi documenti su pagina singola, inoltre, rendono possibile ai lettori l'utilizzo della funzionalità di ricerca del browser.

Screenshot della pagina reference della API di Stripe

Stripe è riuscita a presentare una documentazione vasta in una pagina singola facile da navigare.

Navigazione persistente

Lasciate sempre visibile la navigazione. Gli utenti non vogliono fare scrolling per cercare la barra di navigazione scomparsa.

Layout multi-colonna

I layout a 2 o 3 colonne hanno la navigazione a sinistra e le informazioni e gli esempi sulla destra. Rendono più semplice la comprensione mostrando gli endpoint e gli esempi nel contesto.

Screenshot della reference page della API di Clearbit

Il layout a tre colonne di Clearbit mostra la navigazione persistente (table of contents) sulla sinistra, le reference nel mezzo e gli esempi di codice sulla destra.

Syntax highlighter

Migliorare la leggibilità degli esempi con la syntax highlighting rende il codice più semplice da capire.

Screenshot della pagina di documentazione della API di Plaid

La syntax highlighter in azione sul sito della documentazione della API di Plaid.

Se volete cominciare a sperimentare con un layout per i vostri documenti, dovreste guardare alcuni generatori di documentazione di API gratis e open source.

Per sapere dei pro e dei contro dei vari approcci per l'organizzazione della documentazione dell'API nel contesto dei developer portal, questo è un eccellente articolo di Nordic APIs.

Editing

Tutto quello che scrivete dovrebbe passare attraverso un processo di editing. Si tratta di buon senso per gli articoli e le altre pubblicazioni, ma è altrettanto essenziale per la documentazione tecnica.

Gli autori della documentazione della API dovrebbero puntare a chiarezza e brevità, essere sicuri che tutte le informazioni necessarie siano presenti e che la struttura sia logica e gli argomenti non siano diluiti con contenuti non necessari.

Gli editor dovrebbero fare la revisione della documentazione per correggere errori grammaticali, errori e qualunque altra parte che possa essere difficile da leggere o capire. Dovrebbero anche controllare i documenti rispetto alla vostra style guide per la documentazione tecnica e suggerire dei cambiamenti se necessario.

Una volta che una sezione della documentazione è pronta per essere pubblicata, è una buona idea mostrarla a delle persone nel vostro audience target, specialmente a qualunque developer che non abbia lavorato sulla documentazione. Potrebbero trovare delle inconsistenze e fornire degli insight su quello che manca.

Sebbene il processo di editing possa sembrare un peso quando dovete concentrarvi su così tanti altri aspetti della vostra API, un paio di iterazioni possono fare un'enorme differenza nella versione finale e nell'impressione che fate.

Tenetela aggiornata

Se la documentazione dell'API è datata, gli utenti si sentiranno frustrati nell'imbattersi in feature che non esistono più e in quelle nuove per cui manca la documentazione. Questo può far diminuire rapidamente la fiducia che avete stabilito mettendo così tanto lavoro fin dall'inizio nella vostra documentazione.

Quando fate la manutenzione dei documenti della API, dovreste tenere d'occhio i seguenti aspetti:

  • Feature deprecate. Togliete la documentazione per le feature deprecate e spiegate perché sono state deprecate.
  • Nuove feature. Documentate le nuove feature prima del lancio e assicuratevi che ci sia stato pianificato un tempo sufficiente perché il nuovo contenuto passi attraverso il processo editoriale.
  • Feedback. L'utile feedback che ottenete dal supporto o dalle statistiche dovrebbe riflettersi nei vostri documenti. Ci sono buone probabilità che non riusciate a rendere perfetti i documenti al primo tentativo, ma basandovi su quello che dicono gli utenti, potete migliorarli continuamente.

Perché tutto ciò funzioni, dovrete creare un workflow per mantenere la vostra documentazione. Pensate ai checkpoint e ai processi per gli aspetti menzionati prima, per l'editing e per la pubblicazione. Aiuta anche se riuscite a impostare una routine per rivedere regolarmente i vostri documenti (per es., ogni trimestre).

Seguendo queste “best practice”, potete creare una base solida per la documentazione della vostra API che può essere migliorata continuamente man mano che ottenete più “insight” su come gli utenti interagiscono con essa. Rimanete in ascolto per la seconda parte, in cui vi darò dei consigli su come far diventare eccellente una buona documentazione API.