Conoscere il proprio pubblico<\/h2>\n
Sapere a chi vi rivolgete con i vostri scritti e come poter offrire loro il miglior supporto vi aiuter\u00e0 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.<\/p>\n
La documentazione della API verr\u00e0 probabilmente visitata e usata dai seguenti audience.<\/p>\n
Developer<\/h3>\n
Basandosi sulle loro capacit\u00e0, esperienze e ruoli nei progetti, gli sviluppatori saranno generalmente il gruppo pi\u00f9 grande e pi\u00f9 variegato. Useranno i vostri documenti in modi diversi.<\/p>\n
In Pronovix, abbiamo cominciato a fare dei workshop sui portali per developer con i nostri clienti per aiutarli a imparare di pi\u00f9 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\u00f2 \u00e8 inoltre supportato da una robusta ricerca, come i risultati pubblicati nell’articolo di Stephanie Steinhardt<\/a> provenienti da un programma di ricerca di due anni presso la Merseburg University of Applied Sciences.<\/p>\n Principianti:<\/strong> gli sviluppatori a cui manca una precedente esperienza con la vostra API tendono ad aver bisogno di maggior supporto. Sfrutteranno le guide \u201cquick start\u201d che li incoraggiano a cominciare ad usare la vostra API: tutorial chiari, concisi, passo-passo per gli argomenti pi\u00f9 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\u00e0 molto pi\u00f9 probabile che si impegneranno a imparare ogni sfumatura della vostra API.<\/p>\n Sviluppatori esterni:<\/strong> gli sviluppatori che lavorano gi\u00e0 con la vostra API torneranno ripetutamente alla documentazione e la useranno come materiale di riferimento. Avranno bisogno di informazioni rapide su tutte le funzionalit\u00e0 offerte dalla vostra API, strutturate in una maniera semplice da capire per aiutarli a trovare rapidamente ci\u00f2 di cui hanno bisogno.<\/p>\n Debugger:<\/strong> 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.<\/p>\n Sviluppatori interni:<\/strong> gli API provider tendono a concentrarsi cos\u00ec tanto sul loro pubblico esterno che si dimenticano dei propri sviluppatori. Anche i team interni che lavorano sulla API useranno la documentazione dell’API.<\/p>\n Questi sono solo alcuni degli use case pi\u00f9 comuni.<\/p>\n I decision maker come i CTO<\/strong> e i product manager<\/strong> 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 \u00e8 cruciale per il vostro business che questo gruppo possa trovare facilmente e rapidamente quello che sta cercando.<\/p>\n Sebbene non cos\u00ec 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.<\/p>\n<\/div>\n La base della vostra documentazione della API \u00e8 una spiegazione chiara di ogni call e di ogni parametro<\/strong>.<\/p>\n Come minimo sindacale, dovreste descrivere in dettaglio:<\/p>\n Nessuno legger\u00e0 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 \u201cbest practice\u201d della scrittura per argomento, dovreste includere tutte le informazioni necessarie e correlate nella spiegazione di ogni chiamata.<\/p>\n Context.IO<\/a>, 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.<\/p>\n<\/div>\n 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.<\/p>\n Aggiungete quello che segue alla descrizione di ogni call:<\/p>\n Alcuni studi hanno dimostrato che ad alcuni developer piace immergersi immediatamente nel codice<\/a> 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.<\/p>\n Usare gli esempi giusti \u00e8 un modo sicuro per migliorare la documentazione dell’API. Esplorer\u00f2 dei modi per rendere ottima della documentazione API gi\u00e0 buona usando degli esempi nel mio prossimo post \u201cTen Extras for Great API Documentation\u201d.<\/p>\n<\/div>\n Quando qualcosa non va per il verso giusto durante lo sviluppo, sistemare il problema senza della documentazione dettagliata pu\u00f2 diventare un processo frustrante e che richiede molto tempo. Per rendere questo processo il pi\u00f9 liscio possibile, i messaggi d’errore dovrebbero aiutare gli sviluppatori a capire:<\/p>\n 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).<\/p>\n Questo post da Box<\/a> 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.<\/p>\n<\/div>\n I principianti che cominciano a implementare la vostra API si trovano di fronte molti ostacoli:<\/p>\n Se non rendete semplice il processo di apprendimento per loro, possono sentirsi sopraffatti e si tratterranno dall’approfondire la vostra API.<\/p>\n Molti developer imparano facendo, quindi un’ottima opzione \u00e8 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. \u00c8 meglio presumere che lo sviluppatore non abbia mai sentito prima del vostro servizio.<\/p>\n Le guide quickstart di Stripe<\/a> e Braintree<\/a> sono degli ottimi esempi: entrambe forniscono una panoramica dei task pi\u00f9 probabili che vorrete realizzare mediante l’API, cos\u00ec come dei link ad informazioni rilevanti. Contengono inoltre dei link per contattare qualcuno in caso di bisogno.<\/p>\n<\/div>\n I tutorial sono delle guide dettagliate step by step che coprono funzionalit\u00e0 specifiche che gli sviluppatori possono implementare con la vostra API, come le notifiche SMS, la verifica dell’account, etc.<\/p>\n 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\u00f9<\/em>. In questo modo, gli utenti possono concentrarsi sul task corrente e non saranno sommersi di informazioni di cui non hanno bisogno.<\/p>\n La descrizione degli step dovrebbe essere facile da seguire e concisa. La chiarezza e la brevit\u00e0 supportano il processo di apprendimento e sono una \u201cbest practice\u201d 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\u00f2 creare confusione. Aiutateli rendendo tutte le descrizioni quanto pi\u00f9 possibile semplici da capire.<\/p>\n La guida dettagliata (o walkthrough) dovrebbe essere il pezzo pi\u00f9 piccolo possibile che permetta agli utenti di portare a termine un task. Se un processo \u00e8 troppo complesso, pensate a suddividerlo in pezzi pi\u00f9 piccoli. Questo assicura che gli utenti possano avere l’aiuto di cui hanno bisogno senza passare per step a cui non sono interessati.<\/p>\n I tutorial di Twilio<\/a> spiegano gli use case pi\u00f9 probabili con delle app di esempio in un’ampia variet\u00e0 di linguaggi di programmazione e framework.<\/p>\n<\/div>\n<\/div>\n Per implementare la vostra API, ci sono alcuni argomenti pi\u00f9 ampi che gli sviluppatori dovranno conoscere, per esempio:<\/p>\n 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.<\/p>\n<\/div>\n 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.<\/p>\n La maggior parte dei buoni esempi di documentazione di API usano un layout dinamico perch\u00e9 rende pi\u00f9 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\u00e0 di poter espandere facilmente la vostra documentazione al bisogno.<\/p>\n Se la documentazione della vostra API non \u00e8 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\u00ec. I lunghi documenti su pagina singola, inoltre, rendono possibile ai lettori l’utilizzo della funzionalit\u00e0 di ricerca del browser.<\/p>\n Stripe<\/a> \u00e8 riuscita a presentare una documentazione vasta in una pagina singola facile da navigare.<\/p>\n<\/div>\n Lasciate sempre visibile la navigazione. Gli utenti non vogliono fare scrolling per cercare la barra di navigazione scomparsa.<\/p>\n I layout a 2 o 3 colonne hanno la navigazione a sinistra e le informazioni e gli esempi sulla destra. Rendono pi\u00f9 semplice la comprensione mostrando gli endpoint e gli esempi nel contesto.<\/p>\nDecision maker<\/h3>\n
Altri audience<\/h3>\n
Ricordatevi lo scopo della documentazione<\/h2>\n
\n
Struttura basata sul contesto<\/h3>\n
Esempi<\/h2>\n
\n
Messaggi d’errore<\/h2>\n
\n
Guida quickstart<\/h2>\n
\n
Tutorial<\/h2>\n
![\"Screenshot](\"http:\/\/alistapart.com\/it\/wp-content\/uploads\/sites\/2\/2017\/11\/fig1.png\")
<\/p>\nArgomenti universali<\/h2>\n
\n
Layout e navigazione<\/h2>\n
Layout dinamico<\/h3>\n
Design single page<\/h3>\n
![\"Screenshot](\"http:\/\/alistapart.com\/it\/wp-content\/uploads\/sites\/2\/2017\/11\/fig2.png\")
<\/p>\nNavigazione persistente<\/h3>\n
Layout multi-colonna<\/h3>\n
![\"Screenshot](\"http:\/\/alistapart.com\/it\/wp-content\/uploads\/sites\/2\/2017\/11\/fig3.png\")
<\/p>\n
![\"Screenshot](\"http:\/\/alistapart.com\/it\/wp-content\/uploads\/sites\/2\/2017\/11\/fig4.png\")
<\/p>\n