Pagina della panoramica generale<\/h2>\n
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:<\/p>\n
- \n
- cosa offre la vostra API (ossia, cosa fanno i vostri prodotti),<\/li>\n
- come funziona,<\/li>\n
- come si integra,<\/li>\n
- come scalarla (ossia, limiti di utilizzo, prezzi, supporto e Service Level Agreements).<\/li>\n<\/ul>\n
![\"Screenshot:](\"http:\/\/alistapart.com\/it\/wp-content\/uploads\/sites\/2\/2018\/04\/spotify-api.jpg\")
<\/p>\nLa API documentation di Spotify<\/a> dichiara chiaramente cosa fa la API e come funziona e fornisce dei link a guide e API references organizzati in categorie.<\/p>\n<\/div>\n
Una pagina di panoramica generale \u00e8 indirizzata a tutti i visitatori, ma pu\u00f2 essere particolarmente utile per i decision-maker. Devono vedere il valore del business: spiegategli direttamente perch\u00e9 un’azienda dovrebbe usare la vostra API.<\/p>\n
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.<\/p>\n
Come ha scoperto lo studio \u201cThe role of conceptual knowledge in API usability<\/a>\u201d, senza una conoscenza concettuale, gli sviluppatori hanno delle difficolt\u00e0 nel formulare delle domande efficaci e nel valutare la rilevanza o il significato del contenuto che hanno trovato. Questo \u00e8 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\u00e0 di un’API. La pagina della panoramica pu\u00f2 essere una componente importante per adempiere a questo ruolo.<\/p>\n
![\"Screenshot:](\"http:\/\/alistapart.com\/it\/wp-content\/uploads\/sites\/2\/2018\/04\/braintree-overview.jpg\")
<\/p>\nLa pagina della overview di Braintree<\/a> fornisce una chiara panoramica del loro SDK, insieme a una spiegazione passo-passo visuale di come funziona la loro API.<\/p>\n<\/div>\n<\/div>\n
\nEsempi<\/h2>\n
Per alcuni sviluppatori, gli esempi giocano un ruolo molto importante nel familiarizzare con una API rispetto alle spiegazioni di call e parametri.<\/p>\n
Uno studio recente, \u201cApplication Programming Interface Documentation\u2014What Do Software Developers Want?<\/a>\u201d, 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\u00e0 dei documenti della API.<\/p>\n
Il ruolo degli esempi<\/h3>\n
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.<\/p>\n
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 \u00e8 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.<\/p>\n
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\u00f9 degli esempi che della documentazione perch\u00e9, 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\u00f9 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.<\/p>\n
Migliorate i vostri esempi<\/h3>\n
Dal momento che gli esempi sono dei componenti cos\u00ec cruciali nella documentazione della API, esempi migliori implicano documenti migliori.<\/p>\n
Per assicurare la qualit\u00e0 dei vostri esempi, essi dovrebbero essere completi, programmati professionalmente e funzionare in maniera corretta. Dal momento che gli esempi convogliano molto di pi\u00f9 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.<\/p>\n
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.<\/p>\n
Quando includete degli esempi, avete una variet\u00e0 di formati e approcci tra cui scegliere: esempi auto-generati, applicazioni tipo, client libraries ed esempi in pi\u00f9 linguaggi.<\/p>\n
Esempi auto-generati<\/h4>\n
I tool di auto-documentazione come Swagger Codegen<\/a> e API Blueprint<\/a> 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 \u00e8 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\u00e0.<\/p>\n
Sul blog Readme, si esplorano i tool di auto-doc e i loro limiti<\/a> in maggiore dettaglio attraverso un paio di esempi tratti dal mondo reale.<\/p>\n
Applicazioni campione<\/h4>\n
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\u00e9 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\u00e0 della vostra API ai decision makers. L’iOS Developer Portal di Apple<\/a> offre degli esempi sorgenti buildable ed eseguibili di come portare a termine un task usando una tecnologia particolare in un’ampia variet\u00e0 di categorie.<\/p>\n
Client libraries<\/h4>\n
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\u00e0 base di un’applicazione per essere in grado di interagire con la API. Fornirli \u00e8 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\u00f9 comunemente usati con la loro API, mentre mettono dei link a librerie non supportate, create dalla community, scritte in altri linguaggi meno popolari.<\/p>\n
Esempi in pi\u00f9 linguaggi<\/h4>\n
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\u00f9 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.<\/p>\n<\/div>\n
\nUsabilit\u00e0<\/h2>\n
La documentazione dell’API \u00e8 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\u00f9 semplice da usare possibile. Considerate i seguenti fattori:<\/p>\n
- \n
- Copy and paste:<\/strong> Gli sviluppatori fanno copia e incolla degli esempi di codice per usarli come punto di partenza per le loro implementazioni. Rendete pi\u00f9 semplice questo processo o con un pulsante \u201ccopy\u201d vicino alle sezioni importanti o rendendo semplice evidenziare e copiare le sezioni.<\/li>\n
- Sticky navigation:<\/strong> Se ben implementato, fissare l’indice o un’altra navigazione nella visualizzazione della pagina pu\u00f2 far s\u00ec che gli utenti non si perdano e abbiano controllo quando ritornano verso l’alto.<\/li>\n
- Click:<\/strong> Minimizzate i click tenendo vicini gli uni agli altri gli argomenti correlati.<\/li>\n
- Selettore del linguaggio:<\/strong> 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.<\/li>\n
- URL:<\/strong> 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.\n
![\"Screenshot:](\"http:\/\/alistapart.com\/it\/wp-content\/uploads\/sites\/2\/2018\/04\/stripe-urls.jpg\")
<\/p>\nGrande usabilit\u00e0: La documentazione della API di Stripe<\/a> cambia l’URL dinamicamente man mano che si scorre lungo la pagina.<\/p>\n<\/div>\n
Altra best practice da Stripe: anche il selettore del linguaggio cambia l’URL, cos\u00ec che gli URL portino nella giusta posizione nel giusto linguaggio.<\/p>\n<\/li>\n
- Collaborazione:<\/strong> 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 \u00e8 quello di avere la documentazione su GitHub, ma tenete presente che questo limiter\u00e0 le vostre opzioni di interattivit\u00e0, dal momento che GitHub ospita file statici.<\/li>\n<\/ul>\n<\/div>\n
\nInterattivit\u00e0<\/h2>\n
Fornire un’opzione per gli utenti per interagire con la vostra API attraverso la documentazione migliorer\u00e0 moltissimo l’esperienza dello sviluppatore e dar\u00e0 un’accelerata all’apprendimento.<\/p>\n
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.<\/p>\n
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.<\/p>\n
Un modo pi\u00f9 sofisticato per rendere pi\u00f9 interattiva la vostra documentazione \u00e8 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<\/a>, 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<\/a>.<\/p>\n<\/div>\n
\nAiuto<\/h2>\n
Lo studio che esplorava il modo in cui i software developer interagiscono con la API documentation<\/a> 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.<\/p>\n
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\u00e0, una soluzione help desk direttamente dai vostri doc, per esempio, una live chat con uno staff di supporto.<\/p>\n
Tale studio ha anche evidenziato il ruolo significativo giocato da Stack Overflow<\/a>: 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.<\/p>\n<\/div>\n
\nChangelog<\/h2>\n
Come con tutto il software, le API cambiano e vengono regolarmente aggiornate con nuove feature, bug fix e miglioramenti della performance.<\/p>\n
Quando esce una nuova versione della vostra API, dovete informare dei cambiamenti gli sviluppatori che ci lavorano cos\u00ec che possano reagirvi di conseguenza. Un changelog, chiamato anche \u201cnote di rilascio\u201d, include le informazioni riguardanti le versioni attuali e quelle precedenti, solitamente ordinate per data e per numero di versione, insieme ai cambi associati.<\/p>\n
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.<\/p>\n
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.<\/p>\n
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.<\/p>\n<\/div>\n
\nStatistiche e feedback<\/h2>\n
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.<\/p>\n
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.<\/p>\n
Scoprite attraverso le statistiche quali sono i casi d’uso pi\u00f9 popolari. Osservate quali endpoint vengono usati maggiormente e assicuratevi di dare loro la priorit\u00e0 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 \u00e8 qualcosa che dovete spiegare nella documentazione.<\/p>\n
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?<\/p>\n
Ascoltate il feedback e valutate come potete migliorare la vostra documentazione basandovi su di esso. Il feedback pu\u00f2 arrivare da molti canali diversi: workshop, training, blog post e commenti riguardanti la vostra API, conferenze, interviste con i clienti o studi di usabilit\u00e0.<\/p>\n<\/div>\n
\nLeggibilit\u00e0<\/h2>\n
La leggibilit\u00e0 \u00e8 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\u00f9 difficile con del testo difficile da comprendere.<\/p>\n
Mentre in generale dovreste avere come obiettivo la chiarezza e la brevit\u00e0 fin dal principio, ci sono alcuni aspetti specifici su cui potete lavorare per migliorare la leggibilit\u00e0 della documentazione dell’API.<\/p>\n
Audience:<\/strong> 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\u00e0 familiarit\u00e0 con la funzionalit\u00e0 di trovare rapidamente quello che stanno cercando, per esempio, aggiungete una quick reference organizzata in maniera logica.<\/p>\n
Formulazione:<\/strong> spiegate tutto il pi\u00f9 semplicemente possibile<\/a>. 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\u00f2, 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\u00e0 con il vostro business domain possano ottenere l’aiuto di cui necessitano per comprendere la vostra API.<\/p>\n
Font:<\/strong> sia la dimensione del font sia il tipo di font influenzano la leggibilit\u00e0. Usate titoli brevi per le sezioni e usate il title case per rendere pi\u00f9 semplice scorrerli. Per il testo pi\u00f9 lungo, usate i font sans serif. Nella stampa, i font serif rendono pi\u00f9 semplice la lettura, ma online, i caratteri serif possono confondersi. Optate per font come Arial, Helvetica, Trebuchet, Lucida Sans, o Verdana, che \u00e8 stato disegnato apposta per il Web. Anche il contrasto gioca un ruolo importante: pi\u00f9 alto il contrasto<\/a>, pi\u00f9 facile da leggere sar\u00e0 il testo. Prendete in considerazione l’uso di un font di dimensione leggermente pi\u00f9 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.<\/p>\n
Struttura:<\/strong> 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.<\/p>\n
![\"Screenshot:](\"http:\/\/alistapart.com\/it\/wp-content\/uploads\/sites\/2\/2018\/04\/stripe-anchors.jpg\")
<\/p>\nGrande usabilit\u00e0: linkabilit\u00e0 dimostrata nella documentazione della API di Stripe<\/a>.<\/p>\n<\/div>\n
Scorrevolezza:<\/strong> come sostiene Steve Krug nel suo libro sull’usabilit\u00e0 web, Don\u2019t Make Me Think<\/em><\/a>, uno dei fatti pi\u00f9 importanti \u00e8 che gli utenti web non leggono, scorrono. Per rendere pi\u00f9 semplice la scansione del testo, usate paragrafi brevi, sottolineate le parole importanti e usate liste ogni volta che potete.<\/p>\n
Accessibilit\u00e0:<\/strong> 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<\/a>. Imparate di pi\u00f9 sull’accessibilit\u00e0 web<\/a>, studiate le Web Content Accessibility Guidelines<\/a> e fate del vostro meglio per aderirvi.<\/p>\n<\/div>\n
\nPersonalit\u00e0<\/h2>\n
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 \u201csuonino\u201d e appaiano in sintonia con il vostro brand.<\/p>\n
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\u00e0 nei vostri doc:<\/p>\n
- \n
- Usate il vostro brand book e assicuratevi che i vostri API doc lo seguano alla lettera.<\/li>\n
- 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.<\/li>\n
- 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.<\/li>\n
- Selezionate attentamente i vostri esempi cos\u00ec che riflettano il vostro prodotto nel modo in cui volete. Implementazioni giocose della vostra API creeranno un’impressione diversa rispetto agli use case pi\u00f9 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.<\/li>\n
- Potete inserire alcune immagini (oltre alle illustrazioni) dove possibile, ma assicuratevi che aggiungano qualcosa ai vostri documenti e che non distraggano il lettore.<\/li>\n<\/ul>\n<\/div>\n\n
Pensate al developer portal e oltre<\/h2>\n
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 \u00e8 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.<\/p>\n
In effetti, alcune delle idee discusse prima, come un developer forum o delle sandbox, puntano gi\u00e0 nella direzione della creazione di un developer portal. Un developer portal \u00e8 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.<\/p>\n
Anche se avete gi\u00e0 iniziato a costruire il vostro developer portal, potete ancora trovare dei modi per imparare di pi\u00f9 ed estendere la vostra portata. Partecipate e presentate a conferenze quali DevRelCon<\/a>, Write The Docs<\/a> o API The Docs<\/a> 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<\/a> per saperne di pi\u00f9 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<\/a> che potete seguire per stare aggiornati con l’economia in continuo cambiamento delle API: vi troverete sicuramente anche le vostre fonti di ispirazione.<\/p>\n
- Sticky navigation:<\/strong> Se ben implementato, fissare l’indice o un’altra navigazione nella visualizzazione della pagina pu\u00f2 far s\u00ec che gli utenti non si perdano e abbiano controllo quando ritornano verso l’alto.<\/li>\n
- Copy and paste:<\/strong> Gli sviluppatori fanno copia e incolla degli esempi di codice per usarli come punto di partenza per le loro implementazioni. Rendete pi\u00f9 semplice questo processo o con un pulsante \u201ccopy\u201d vicino alle sezioni importanti o rendendo semplice evidenziare e copiare le sezioni.<\/li>\n