Lukuaika: 9 minuuttia
API:t pyörittävät maailmaa. Kehittäjät käyttävät API:ita lähes päivittäin – joidenkin arvioiden mukaan he käyttävät API:iden kanssa työskentelyyn yli 10 tuntia viikossa. Tämä ei koske vain niiden käyttöä, vaan myös niiden tutkimista, tuen googlettamista, arvostelujen tutkimista ja tietysti dokumentaation penkomista. Se, kuinka selkeä, helppo, hyödyllinen ja tuettu sovellusliittymäsi on, määrittää koko kehittäjäkokemuksen (DX) – tunnereaktion, jonka kehittäjät saavat tuotetta kohtaan. API-taloudessa hyvä kehittäjäkokemus on olennaisen tärkeää. API:t, jotka auttavat kehittäjiä menestymään ja joita on ilo käyttää, saavat paljon käyttäjiä ja nousevat kilpailijoiden yläpuolelle. Ja se alkaa juuri sillä hetkellä, kun he avaavat dokumentaation ensimmäistä kertaa.
Katso tämä video, josta saat johdatuksen API-teknologiaan
Tänään puhumme siitä, miten API-dokumentaatiossa voidaan edistää positiivista kehittäjäkokemusta. Mutta ensin meidän on ymmärrettävä, mikä tekee huonoista API-dokumenteista huonoja.
Mitä kehittäjät vihaavat API-dokumentaatiossa
Kehittäjäyhteisö on intohimoinen. Se suhtautuu erityisen intohimoisesti asioihin, joista se ei pidä. Jos he eivät pidä API:sta, se johtuu useimmiten rosoisesta dokumentaatiosta, vaikka tuote olisikin itse asiassa loistava. Seuraavassa on muutamia yleisiä ongelmia, joita kehittäjät kokevat API-dokumenttien kanssa.
Sitä ei ole kirjoitettu yksinkertaisella inhimillisellä kielellä. Tämä on yleinen ongelma automaattisesti luoduissa dokumenteissa tai dokumenteissa, jotka tekijät ovat laiminlyöneet. Vaikka monet dokumenttien luontityökalut tekevät hyvää työtä koodin kommentoinnissa, ne eivät voi korvata kehittäjän tai teknisen kirjoittajan kirjoittamia varsinaisia englanninkielisiä selityksiä.
Se sisältää hyvin vähän koodinäytteitä. Tämä on toinen ääripää, jossa selityksiä on runsaasti, mutta esimerkkejä varsinaisesta koodista on minimaalisesti.
Se on saatavilla vain rekisteröityneille käyttäjille. Tämä ei-niin-nopea manööveri ei tee mitään markkinoinnillesi. Se vain turhauttaa ihmisiä, jotka haluavat tietää, mitä API:si tekee, ennen kuin päättävät, haluavatko he sen (kuten kuka tahansa tervejärkinen ihminen tekisi).
Se on liian pitkä/ei löydy/epätarkka/ei ole päivitetty vuosiin jne. Hyvien dokumenttien luominen on lähes yhtä tärkeää kuin hyvän API:n rakentaminen. Koska huonosti kirjoitetut dokumentit tai sellaiset, joita ei löydy yksinkertaisesti googlaamalla ”Product API” epäonnistuvat koko kehitystyössä. Jos olet kiinnostunut, olemme jo hahmotelleet teknisen dokumentoinnin erityispiirteitä yleisesti. API-dokumentit ansaitsevat kuitenkin oman artikkelin. Miten siis kirjoitat loistavat API-dokumentit?
Valitaan spesifikaatio-ohjattu kehitys
Spesifikaatio-ohjattu kehitys (SDD) on samankaltaista kuin testiohjattu kehitys, jossa kirjoitetaan testitapauksia kullekin ominaisuudelle ja sen jälkeen kirjoitetaan koodia, jonka pitäisi läpäistä ne. SDD:ssä luot dokumentteja tai ainakin joitain osia niistä rinnakkain API:n rakentamisen kanssa, usein noudattaen tiettyä API:n kuvausmuotoa, jota kutsutaan spesifikaatioksi.
Asiointirajapinnan spesifikaatio on ikään kuin tulevien dokumenttiesi malli, yhtenäinen kieli, joka kuvaa API:n suunnittelun, selittää, miten se toimii ja mitä siltä voi odottaa. On olemassa muutamia spesifikaatioita, kuten RAML (RESTful API Modeling Language), OpenAPI (entinen Swagger) ja API Blueprint, mutta meneillään on trendi, jossa kaikki spesifikaatiot yhdistetään OpenAPI:n konepellin alle.
Näissä spesifikaatioissa on valmiita dokumentointityökaluja, jotka mahdollistavat dokumenttien kirjoittamisen ja hallinnan. Esimerkiksi API Console luo automaattisesti dokumentteja RAML- ja OpenAPI-muodoista ja auttaa sinua käyttämään niitä olemassa olevassa web-sovelluksessasi tai itsenäisenä sovelluksena.
API Consolen avulla voit rakentaa verkkoportaalin API-dokumenteillesi RAML- ja OpenAPI-spesifikaatioista
Lähde: API Console: Pawel Psztyc
Vaihtoehtona perinteisille API-dokumenttiratkaisuille, kuten WordPress- tai Drupal CMS -ohjelmistoille, API-spesifikaatiotuotteet ovat avoimen lähdekoodin tuotteita, jotka on luotu dev-yhteisön toimesta dev-yhteisöä varten, joissa on parserit eri ohjelmointikielillä ja jatkuva luojien tuki.
Kirjoita aloittelevalle tasolle
On syy, miksi kehittäjät eivät yleensä kirjoita teknistä dokumentaatiota itse – se on teknisten kirjoittajien, teknisten näkökohtien asiantuntijoiden, tehtävä. He ovat asiantuntijoita teknisten näkökohtien kääntämisessä helppolukuiseksi. Mutta jopa teknisillä kirjoittajilla on taipumus vuotaa tekstiin hieman jargonia.
Asiointirajapinta, kuten mikä tahansa ohjelmistotuote, luodaan tietylle yleisölle. Mutta dokumentoinnin yleisö on laaja. Dokumentaation käyttäjiä on kolme pääryhmää:
- kehittäjät, jotka ovat läheisessä vuorovaikutuksessa dokumenttien kanssa
- päätöksentekijät, kuten teknologiapäälliköt ja ratkaisuarkkitehdit, jotka haluavat määrittää nopeasti, onko API:si hyvä sovittaa nopeasti
- seurantahenkilöt, kuten journalistit, tekniset kirjoittajat ja jopa kilpailijat, jotka eivät välttämättä käytä API:tasi koskaan.
Jopa näiden ryhmien sisällä on ihmisiä, joilla on erilaisia taitoja, rooleja ja tarpeita, ja kaikilla heistä pitäisi olla positiivinen kokemus asiakirjoista. Miten kohdennat heidät kaikki? Kohdistamalla vähiten kokeneet käyttäjät. Miten siis kirjoitat asiakirjoja vasta-alkajille?
Aloita mahdollisuuksista eikä niinkään teknisistä yksityiskohdista. Tervehdi käyttäjiä mukaansatempaavalla tarinalla, jossa kerrot, miten API:si voi rikastuttaa heidän tuotettaan tai tehdä kehittäjien elämästä kymmenkertaisesti helpompaa.
Amazon Alexa API:n dokkarit aloitetaan selittämällä, mitä Alexa tekee ja mitä hyötyä se voi tuoda asiakkaalle
Näytä, mistä aloittaa. API-dokumentit ovat tunnetusti liian ylivoimaisia ja olettavat, että käyttäjillä on laaja kokemus API:ista. Aloitusosio on pakollinen, ja se tulisi kirjoittaa kärsivällisesti potentiaalista käyttäjää varten.
Facebook tarjoaa selkeän viitteen aloittelijoille ja seuraa aloitusprosessia askel askeleelta
Luo ohjeet yleisimpiin käyttötapauksiin. Tiedät todennäköisesti jo, mihin toimintoihin ihmiset käyttävät APIasi. Luo niitä käsitteleviä erillisiä osioita ja sisällytä niihin esimerkkiviestejä.
Käytä keskustelevaa sävyä. Kehittäjäyhteisö on rento ja epämuodollinen, joten he eivät arvosta kuivaa yrityskieltä, vaikka se kuulostaisi ”ammattimaisemmalta”. Hyvät dokumentit puhuttelevat aina ihmisiä.
Kouluta ulkoisista työkaluista. Jos API-rajapintasi edellyttää kolmansien osapuolten tuotteiden ja käsitteiden, kuten OAuthin tai npm:n, käyttöä ja ymmärtämistä, sisällytä linkkejä dokumentteihin tai asennusoppaisiin.
Tee siitä helposti opittavaa. API-dokumentit eivät ole IKEAn kokoamisohjeita,;ne ovat oppimisen lähde. Rikastuta dokumentaatiota usein kysytyillä kysymyksillä, opetusohjelmilla, blogeilla ja mahdollisuuksien mukaan jopa videoilla.
Sisällytä pakolliset osiot
Swaggerin kehittäjä SmartBear teki vuonna 2019 kyselyn API-kehittäjille ja -käyttäjille. He selvittivät, mitä dokumentaatio-ominaisuuksia pidetään yhteisössä tärkeimpinä, ja antoivat meille listan pakollisista dokumentaatio-osioista, jotka kehittäjät haluavat kattaa. Käymme läpi joitakin niistä.
SmartBear teki kyselytutkimuksen 3 000 API-käyttäjälle
Examples. Esimerkit esitetään yleensä koodinpätkinä, jotka ovat riittävän hyödyllisiä, mutta joista voidaan tehdä vielä käytännöllisempiä. Esimerkiksi sisällyttämällä mukaan kenttien transkriptio, kuten Medium-dokumenteissa tehdään, tai jopa luomalla mock API, jota kehittäjät voivat testata ja käyttää tekemällä oikeita kutsuja. Mock API:t voidaan helposti jakaa URL-osoitteella tai GitHubissa, ja jos ne tehdään tietyllä tarkkuudella, niitä voidaan jopa käyttää lopullisessa tuotteessa.
Tila ja virheet. On olemassa vakiotilakoodeja ja API-kohtaisia tilakoodeja. On hyvä idea sisällyttää kaikki virheet, jotka API:si voi laukaista. Virheet laitetaan usein dokumenttien omalle sivulle, mutta on järkevää monistaa osa niistä suoraan päätepisteen alle, jossa ne tulevat eniten esiin.
Autentikointi. Useimmat API-dokumentit alkavat autentikoinnista ja valtuutuksesta. Sen pitäisi kattaa tiedot siitä, miten API-avain hankitaan ja miten pyynnöt todennetaan, mukaan lukien mahdolliset virheet, tunnisteiden vanhenemisaika ja selitys todennuksen herkkyydestä (periaatteessa muistutus siitä, että avaimia ei voi jakaa ja missä niitä voidaan käyttää).
HTTP-pyynnöt. Verkkopyyntöjen esittäminen HTTP-muodossa on dokumentaation vähimmäistaso. Yleensä oletetaan, että kehittäjät osaavat lähettää HTTP-pyynnöt valitsemallaan kielellä, mutta joskus API:n luojat sisällyttävät pyyntöjä eri kielillä. Tämä voidaan tehdä automaattisesti API-spesifikaatiotyökalujen ja Postmanin kaltaisten API-hallintatyökalujen avulla.
Käytä alan standardin mukaista ulkoasua
Jos käytät dokumentaatiogeneraattoria, ulkoasu on jo päätetty puolestasi. Useimmat API-dokumentit näyttävät ja tuntuvat samalta. Jos olet käyttänyt muutamaa sellaista, tiedät, miten lähestyä uusia dokumentteja. Silti suurten tietomäärien järjestäminen, niiden löytäminen ja helppo navigointi on monimutkainen tehtävä. Tässä on joitakin toimivimman ulkoasun ominaisuuksia.
Dynaaminen ulkoasu. Voit tunnistaa vanhentuneen API:n sen staattisesta dokumentaatiosta. Yksisivuinen tai edes PDF-dokumentti ei riitä vuonna 2020. Dynaamisia dokumentteja on helppo selata, päivittää ja merkitä kirjanmerkkeihin.
Kiinnittyvä sisältö. Ei, navigointipalkki ei häiritse eikä varasta arvokasta näyttötilaa. Pidä sisältö aina näkyvillä.
Kolmasarakkeinen ulkoasu. Tätä asettelua ei käytetä kovin usein, mutta se mahdollistaa toisen oikeanpuoleisen sarakkeen koodiesimerkkejä varten. Tämä on tietysti järkevää vain, jos sinulla on paljon tekstiä ja haluat korostaa koodia, jotta käyttäjien ei tarvitse selata edestakaisin tai vaihtaa välilehtien välillä.
HubSpotin API-asiakirjoissa käytetään kolmisarakkeista asettelua
Käytä kontrastivärejä syntaksille. Kehittäjät käyttävät paljon aikaa koodiesimerkkiesi tarkasteluun, joten tee niistä helppolukuisia ja erottele eri osat väreillä.
Tämä esimerkki Facebookin Graph API -dokumenteista osoittaa myös, miten voit käyttää eri välilehtiä SDK:iden väliseen valintaan
Tallennettu vieritystila. Tämä on pieni yksityiskohta, jota kuka tahansa kehittäjä arvostaa. Voit myös käyttää ankkurilinkkejä sivun eri osien määrittämiseen, jos he kopioivat URL-osoitteen.
Kannusta palautteeseen. Asiakirjasi ovat tärkein markkinointivälineesi – jos ihmiset pitävät niistä, he käyttävät API:tasi enemmän kuin kilpailijoiden API:ita ja kasvattavat yhteisöä sen ympärille. Tavallinen ”Oliko tästä sivusta apua?” -viesti kertoo, kuinka hyvin vastaat kehittäjien kysymyksiin, ja palautelomaketta käytetään usein niin kauan kuin toimitat sen.
Älä hylkää dokumentteja
Vanhentuneet dokumentit ovat API-käyttäjien suurin kiusankappale. Se on myös yksi yleisimmistä virheistä. Kehittäjät kirjoittavat päivityksistä usein useita päiviä niiden käyttöönoton jälkeen, joskus rajoittuen muutamaan lauseeseen. Tämä johtuu siitä, että dokumenttien päivittämiselle ei ole vakiintunutta prosessia, eikä kukaan ole siitä vastuussa. Näin varmistat säännölliset ja hyödylliset dokumenttipäivitykset.
Valmista dokumentit ennen päivityksiä. Tee siitä ylimääräinen vaihe julkaisusuunnitelmassasi, älä ota niitä käyttöön ennen kuin sinulla on hyvin kirjoitetut, yksityiskohtaiset ja muokatut kappaleet päivitysten esittelyä varten.
Poista säännöllisesti vanhentuneet tiedot. Dokumentit on tarkistettava usein, vähintään muutaman kuukauden välein. Käyttäjäpalauteominaisuuksien avulla voit havaita epäjohdonmukaisuudet aikaisemmin, ja aina pitäisi olla tiimin jäsen, joka vastaa niiden tarkistamisesta ja päivityksiin reagoimisesta.
Käytä analytiikkaa dokumenttien parantamiseen. Tavallinen API-analytiikka kertoo sinulle, mitä päätepisteitä käytetään useammin, joten voit keskittyä tiettyihin dokumentaation osiin ja tarjota enemmän hyödyllistä tietoa tai luoda erityisiä opetusohjelmia. Seuraa käyttötapauksia, joihin API-rajapintojasi käytetään, koska sen avulla voit laajentaa arvolupausta ja päivittää dokumentteja useampiin mahdollisuuksiin.
Hyviä API-dokumentaation esimerkkejä
Täällä on valtavasti hyviä dokumentteja, joihin voi tutustua ja joista voi oppia. Niiden esimerkkien lisäksi, joita olemme jakaneet koko artikkelissa, tässä on vielä muutama esimerkki, joista voit nauttia ja jotka voit ottaa huomioon.
Mediumin API-dokumentaatio
Mediumin API-dokumentit eivät välttämättä noudata kaikkia tänään luettelemiamme sääntöjä, mutta ne ovat loistavia tämän API:n tukemalle rajoitetulle toiminnallisuudelle – julkaisujen lähettämiselle ja etsimiselle Mediumissa. Ne jaetaan GitHubissa, niiden sisältö on todella lyhyt mutta selkeä, ja niissä on runsaasti esimerkkejä, ja jokainen niistä päättyy kaikkien koodissa mainittujen parametrien transkriptioon, mukaan lukien mahdolliset virheet. Se on huomattavan yksinkertainen, mutta luotettava – kaikki ehdotukset voi tehdä suoraan GitHubissa, ja dokumentteja päivitetään säännöllisesti.
Mailchimpin API-dokumentaatio
Mailchimp ymmärtää, että suurin osa sen kohderyhmästä on markkinointialan ammattilaisia, ja se käyttää sellaista kieltä, jonka avulla myös ei-tekniset ihmiset ymmärtävät, miten sen API-rajapinnoilla työskennellään. Nopealla silmäyksellä jokainen osio noudattaa samaa rakennetta:
- mitä päätepiste tekee ja mitä oppaan avulla käyttäjät voivat tehdä
- mitä tarvitset – mahdolliset käyttöoikeudet tai tilit, jotka käyttäjän on ensin hankittava
- mitä kukin toiminto on tekstimuotoisella kuvauksella, koodiesimerkillä useilla kielillä ja toisinaan kuvakaappauksilla käyttöliittymästä.
Jokaista koodinpätkää varten on jopa kopioi-painike – yksityiskohta, jota ei-teknikot varmasti arvostavat.
Twilion API-dokumentaatio
Twiliolla on tunnetusti hyvät API-dokumentit. Tosin dokumentit ovat vain jäävuoren huippu kaikesta Twilion jakamasta avusta – tarjolla on SDK:t useilla kielillä ja esimerkkisovelluksia iOS:lle, Androidille ja webille. Ensinnäkin ne noudattavat kolmen sarakkeen logiikkaa, jossa koodi on suoraan oppaan oikealla puolella. Yksinkertaisimmat toiminnot selitetään yksityiskohtaisesti ja tonneittain linkkejä lisätietoja ja kuvakaappauksia varten. Palautteeseen kannustetaan myös ”Arvioi tämä sivu” -painikkeella ja linkeillä tukitiimiin ja tagiin StackOverflow’ssa.
Spotifyn API-dokumentaatio
Vaikka Spotifyn web-API-dokumentaatio on hyvin tyypillistä, Spotify for Developers -alustassaan heillä on paljon lisätietoa. Siellä on demoja perustoiminnoille, mock-sovelluksia, Spotify API:n ja widgettien avulla rakennettuja live-esimerkkejä, wrappereita eri ohjelmointikielille ja tietenkin konsoli. Konsoli on periaatteessa interaktiivinen dokumentaatio, johon voit täyttää omia (tai esimerkkitietojasi) ja tutkia päätepisteitä livenä. Tehokkaat tuotteet yhdessä vahvan tietopohjan kanssa tekevät Spotifysta luotettavan kumppanin, jonka kanssa kehittäjät työskentelevät mielellään.
Käsittele dokkareita huolella
Dokumentaatio on ainoa kosketuspiste, joka sinulla on suurimpaan osaan kohderyhmästäsi nähden, joten sinun on opeteltava viestimään selkeästi sen kautta. Paras vinkki tässä on tehdä siitä jonkun työtehtävä. Usein kyse on teknisestä kirjoittajasta, joka osaa puhua eritaitoisille yleisöille, joka osaa kääntää kehittäjien sanat käyttökelpoisiksi kohdiksi ja joka valvoo asiakirjojen oikea-aikaista ylläpitoa ja päivittämistä. Hyvän dokumentaation hallinta on kuitenkin mahdollista myös ilman asiantuntijaa henkilöstössäsi. API-hallintatyökaluilla, kuten Swagger UI:lla, Spotlightilla, Apiarylla ja dokumenttien määrittelytyökaluilla on laaja toiminnallisuus, joka auttaa sinua tekemään dokumentteja, joita kehittäjät rakastavat.