Læsetid: 9 minutter
API’er får verden til at dreje rundt. Udviklere bruger API’er næsten hver dag – ifølge nogle skøn bruger de hele 10+ timer om ugen på at arbejde med API’er. Dette dækker ikke kun brugen af dem, men også research, googling efter support, studier af anmeldelser og selvfølgelig rode rundt i dokumentationen. Hvor klar, nem, nyttig og understøttet din API er, er afgørende for hele udvikleroplevelsen (DX) – en følelsesmæssig reaktion, som udviklerne har på produktet. I API-økonomien er en god udvikleroplevelse af grundlæggende betydning. API’er, der hjælper udviklere med at få succes og er en fornøjelse at bruge, vil få masser af brugere og hæve sig over konkurrenterne. Og det starter præcis i det øjeblik, hvor de åbner dokumentationen for første gang.
Se denne video for at få en introduktion til API-teknologien
I dag vil vi tale om, hvordan man fremmer en positiv udvikleroplevelse i API-dokumentationen. Men først skal vi forstå, hvad der gør dårlige API-dokumentationer.
Hvad udviklere hader i API-dokumentation
Det udviklerfællesskab er et lidenskabeligt fællesskab. Det er specielt passioneret omkring de ting, de ikke kan lide. Hvis de ikke kan lide et API, er det for det meste på grund af junky docs, selv om produktet faktisk er fantastisk. Her er nogle almindelige problemer, som udviklere har med API-dokumenter.
Det er ikke skrevet med simpelt menneskeligt sprog. Dette er et almindeligt problem for automatisk genererede docs eller docs, der er forsømt af skaberne. Selv om mange værktøjer til dokumentationsgenerering gør et godt stykke arbejde med at kommentere koden, kan de ikke erstatte egentlige forklaringer på engelsk skrevet af en udvikler eller teknisk skribent.
Den har meget få kodeeksempler. Dette er en anden ende af spektret, hvor forklaringerne er rigelige, men der er minimale eksempler på den faktiske kode.
Det er kun tilgængeligt for registrerede brugere. Denne ikke så smarte manøvre gør intet for din markedsføring. Den frustrerer kun de mennesker, der gerne vil vide, hvad din API gør, før de beslutter, om de vil have den (som enhver fornuftig person ville gøre).
Den er for lang/kan ikke findes/umulig/ikke korrekt/er ikke blevet opdateret i årevis, osv. Det er næsten lige så vigtigt at lave gode dokumenter som at bygge et godt API. Fordi dårligt skrevne dokumentationer eller dem, der ikke kan findes ved blot at google “Product API”, er en fiasko for hele udviklingsindsatsen. Hvis du er interesseret, har vi allerede skitseret de specifikke aspekter af teknisk dokumentation generelt. Men API-dokumentation fortjener en særlig artikel. Så hvordan skriver du gode API-dokumenter?
Adopt spec-driven development
Spec-driven development (SDD) svarer til test-driven development, hvor du skriver testcases for hver funktion og derefter skriver kode, der skal bestå dem. I SDD opretter du dokumentationen eller i det mindste nogle dele af den sideløbende med opbygningen af en API, ofte efter et bestemt API-beskrivelsesformat kaldet en specifikation.
En API-specifikation er som en skabelon for din fremtidige dokumentation, det ensartede sprog, der beskriver designet af din API, forklarer, hvordan den fungerer, og hvad du kan forvente af den. Der findes nogle få specifikationer, såsom RAML (RESTful API Modeling Language), OpenAPI (tidligere Swagger) og API Blueprint, men der er en tendens til at kombinere alle specifikationer under motorhjelmen af OpenAPI.
Disse specifikationer har forudindbyggede dokumentationsværktøjer, der gør det muligt at skrive og administrere dine dokumenter. API Console genererer f.eks. automatisk dokumenter fra RAML- og OpenAPI-formater og hjælper dig med at køre det på din eksisterende webapplikation eller som en selvstændig app.
API Console lader dig bygge en webportal til dine API-dokumenter fra RAML- og OpenAPI-specifikationer
Kilde: API-specifikationsprodukter er open source, skabt af udviklerfællesskabet til udviklerfællesskabet, har parsere i forskellige programmeringssprog og konstant support til udviklere.
Skriv til begynderniveauet
Der er en grund til, at teknisk dokumentation normalt ikke skrives af udviklere selv – det er opgaven for tekniske skribenter, der er eksperter i at oversætte tekniske aspekter til et læsbart format. Men selv tekniske skribenter har en tendens til at lække en smule jargon ind i teksten.
En API som ethvert softwareprodukt er skabt til en bestemt målgruppe. Men målgruppen for dokumentation er stor. Der er tre hovedgrupper af dokumentationsbrugere:
- udviklere, der vil interagere intimt med dokumentationen
- beslutningstagere som CTO’er og løsningsarkitekter, der hurtigt vil afgøre, om din API vil være en god løsning
- observatører som journalister, tekniske skribenter og endda konkurrenter, der ikke nødvendigvis vil bruge din API nogensinde.
Og selv inden for hver af disse grupper er der folk med forskellige færdigheder, roller og behov, og de skal alle have en positiv oplevelse med dokumentationen. Hvordan henvender man sig til dem alle? Ved at målrette sig mod de mindst erfarne brugere. Så hvordan skriver man dokumenter til en nybegynder?
Start med mulighederne frem for de tekniske detaljer. Hils brugerne med en overbevisende historie, der fortæller, hvordan din API kan berige deres produkt eller gøre udviklernes liv ti gange nemmere.
Amazon Alexa API-dokumentation starter med at forklare, hvad Alexa gør, og hvilken fordel det kan give kunden
Vis, hvor du skal starte. API-dokumenter er berygtede for at være for overvældende og forudsætter, at brugerne har stor erfaring med API’er. Afsnittet om at komme i gang er obligatorisk, og det bør være skrevet med tålmodighed for en potentiel bruger.
Facebook giver en klar reference for begyndere og følger trin for trin processen for at komme i gang
Skab instruktioner for de mest almindelige anvendelsestilfælde. Du ved sikkert allerede, hvilke funktioner folk bruger dit API til. Opret separate afsnit, der omhandler dem, og medtag eksempler på meddelelser der.
Brug en konversationstone. Udviklermiljøet er afslappet og uformelt, så de vil ikke sætte pris på tørt firmasprog, selv om det lyder mere “professionelt”. Gode dokumenter taler altid til mennesker.
Uddann dig om eksterne værktøjer. Hvis dit API kræver brug og forståelse af tredjepartsprodukter og -koncepter som OAuth eller npm, skal du inkludere links til dokumentationen eller installationsvejledninger.
Gør det nemt at lære. API-dokumenter er ikke IKEA-monteringsvejledninger; de er læringskilden. Berig din dokumentation med FAQ’er, tutorials, blogs og endda videoer, når det er muligt.
Indarbejd must-have-sektioner
I 2019 foretog SmartBear, udvikleren af Swagger, en undersøgelse blandt API-udviklere og -brugere. De fandt ud af, hvilke dokumentationsfunktioner der anses for at være de vigtigste i fællesskabet, hvilket giver os en liste over de must-have dokumentationsafsnit, som udviklere ønsker at dække. Vi gennemgår nogle af dem.
SmartBear har undersøgt 3.000 API-udøvere
Eksempler. Eksempler præsenteres normalt som kodestykker, som er nyttige nok, men som kan gøres endnu mere praktiske. For eksempel ved at inkludere en udskrift af felter, som det er gjort i Medium-dokumenter, eller endda ved at oprette et mock-API, som udviklere kan teste og bruge ved at foretage rigtige opkald. Mock API’er kan nemt deles via en URL eller på GitHub, og hvis det er gjort til et vist detaljeringsniveau, kan de endda bruges i det endelige produkt.
Status og fejl. Der er standardstatuskoder og dem, der er specifikke for dine API’er. Det er en god idé at medtage alle fejl, der kan udløses af dit API. Fejl lægges ofte på en dedikeret side i dokumentationen, men det giver mening at duplikere nogle af dem direkte under slutpunktet, hvor de dukker mest op.
Authentificering. De fleste API-dokumenter starter med autentificering og autorisering. Det bør dække info om, hvordan man får en API-nøgle, og hvordan man autentificerer anmodninger, herunder mulige fejl, udløbstider for tokens og en forklaring på autentificeringsfølsomhed (grundlæggende minder om, at nøgler ikke kan deles, og hvor de kan bruges).
HTTP-anmodninger. Tilvejebringelse af webanmodninger i HTTP er det absolutte minimum for dokumentation. Det antages normalt, at udviklerne ved, hvordan de skal sende HTTP-forespørgsler på deres foretrukne sprog, men nogle gange inkluderer API-skaberne forespørgsler på forskellige sprog. Dette kan gøres automatisk via API-specifikationsværktøjer og API-håndteringsværktøjer som Postman.
Brug industristandardlayout
Hvis du bruger en dokumentationsgenerator, er layoutet allerede besluttet for dig. De fleste API-dokumenter ser ud og føles ens. Hvis du har brugt et par stykker, ved du, hvordan du skal gribe nye dokumentationsdokumenter an. Alligevel er det en kompleks opgave at organisere store datamængder, gøre dem findbare og lette at navigere i, en kompleks opgave. Her er nogle af funktionerne i det mest funktionelle layout.
Dynamisk layout. Du kan genkende en forældet API på dens statiske dokumentation. En enkelt side eller endda et PDF-dokument er ikke nok i 2020. Dynamiske dokumenter er nemme at kigge igennem, opdatere og bogmærke.
Sticky indhold. Nej, navigationslinjen distraherer ikke, og den stjæler heller ikke kostbar plads på skærmen. Hold altid indholdet inden for synsvidde.
Trekolonne-layout. Dette layout bruges ikke særlig ofte, men giver dig mulighed for at have endnu en kolonne til højre til kodeeksemplerne. Det giver selvfølgelig kun mening, hvis du har et væld af tekst og ønsker at fremhæve kode, så brugerne ikke behøver at scrolle frem og tilbage eller skifte mellem faner.
HubSpot API-dokumentation bruger et layout med tre kolonner
Brug kontrastfarver til syntaks. Udviklere bruger meget tid på at kigge på dine kodeeksempler, så gør dem læselige og adskil forskellige komponenter ved hjælp af farver.
Dette eksempel fra Facebooks Graph API-dokumentation viser også, hvordan du kan bruge forskellige faner til at vælge mellem SDK’er
Saved scroll state. Dette er en lille detalje, som alle udviklere vil sætte pris på. Du kan også bruge ankerlinks til at angive forskellige sektioner af siden, hvis de kopierer URL’en.
Opfordrer til feedback. Dine dokumenter er dit vigtigste markedsføringsværktøj – hvis folk elsker dem, vil de bruge dit API frem for konkurrenternes og drive fællesskabet omkring det. Den sædvanlige “Var denne side nyttig?”-meddelelse giver dig mulighed for at vide, hvor godt du tager fat på udviklernes spørgsmål, og feedbackformularen vil blive brugt ofte, så længe du leverer varen.
Lad ikke dine dokumenter i stikken
Odated docs er API-brugernes største irritationsmoment. Det er også en af de mest almindelige fejltagelser. Udviklere skriver ofte om opdateringer flere dage efter, at de er rullet ud, og nogle gange begrænser de sig til et par sætninger. Det sker, fordi der ikke er nogen etableret proces for opdateringer af dokumentationen, og fordi det ikke er nogens ansvar. Her er hvordan du sikrer regelmæssige og nyttige doc-opdateringer.
Forbered docs før opdateringerne. Gør det til et ekstra trin i din lanceringsplan, lad være med at rulle dem ud, før du har velskrevne, detaljerede og redigerede afsnit til at introducere dine opdateringer.
Fjern jævnligt forældede data. Dokumentationen skal gennemgås ofte, mindst en gang med et par måneders mellemrum. Med funktioner til brugerfeedback kan du opdage uoverensstemmelser tidligere, og der bør altid være et teammedlem, der er ansvarlig for at gennemgå dem og reagere på opdateringer.
Brug analyser til at forbedre dokumenterne. Standard API-analyser vil fortælle dig, hvilke endpoints der bruges hyppigst, så du kan fokusere på visse dele af dokumentationen og give mere nyttig information eller oprette dedikerede tutorials. Overvåg de brugssituationer, som dine API’er bruges til, for det vil give dig mulighed for at udvide værditilbuddet og opdatere dokumentationen med flere muligheder.
Gode eksempler på API-dokumentation
Der er tonsvis af gode dokumentationer at udforske og lære af. Ud over de eksempler, som vi har delt i hele artiklen, er her nogle flere, som du kan nyde og tage til efterretning.
Medium API-dokumentation
Medium API-dokumentation overholder ikke nødvendigvis alle de regler, vi har nævnt i dag, men de er gode til den begrænsede funktionalitet, som denne API understøtter – offentliggørelse og søgning af publikationer på Medium. De deles på GitHub, har virkelig kort, men klart indhold med tonsvis af eksempler, der hver især slutter med en udskrift af alle parametre, der er nævnt i koden, herunder mulige fejl. Det er bemærkelsesværdigt simpelt, men pålideligt – alle forslag kan fremsættes direkte på GitHub, og dokumentationen opdateres regelmæssigt.
Mailchimp API-dokumentation
Mailchimp er klar over, at størstedelen af dets målgruppe er marketingprofessionelle, og bruger et sprog, der gør det muligt for selv ikke-tekniske personer at forstå, hvordan man arbejder med dets API’er. Overordnet set følger hvert afsnit den samme struktur:
- hvad et endpoint gør, og hvad vejledningen vil lade brugerne gøre
- hvad du skal bruge – eventuelle adgangsrettigheder eller konti, som en bruger skal have først
- hvad hver funktion er med en tekstbeskrivelse, et kodeeksempel på flere sprog og nogle gange skærmbilleder af grænsefladen.
Der er endda en knap til at kopiere for hvert stykke kode – en detalje, som ikke-teknologer helt sikkert vil sætte pris på.
Twilio API-dokumentation
Twilio har som bekendt gode API-dokumenter. Selv om dokumentationen kun er toppen af isbjerget af al den hjælp, Twilio deler ud af – der er SDK’er på flere sprog og prøveapps til iOS, Android og web. Først og fremmest følger de tre-kolonne-logikken med koden direkte til højre i vejledningen. De enkleste handlinger er forklaret med detaljer og tonsvis af links til yderligere oplysninger og skærmbilleder. Der opfordres også til feedback via en “Rate this page”-knap og links til supportteamet og tagget på StackOverflow.
Spotify API-dokumentation
Og selv om Spotifys web-API-dokumentation er meget typisk, har de en masse yderligere oplysninger i deres Spotify for Developers-platform. Der er demoer for grundlæggende funktioner, mock apps, live-eksempler bygget ved hjælp af Spotify API’er og widgets, wrappers til forskellige programmeringssprog og selvfølgelig konsollen. Konsollen er i princippet en interaktiv dokumentation, hvor du kan udfylde dine (eller eksempler på) data og udforske endpoints live. Effektive produkter sammen med en stærk vidensbase gør Spotify til en pålidelig partner, som udviklere gerne arbejder sammen med.
Behandl docs med omhu
Dokumentation er det eneste kontaktpunkt, du vil have med de fleste af dine målgrupper, så du skal lære at kommunikere klart gennem den. Det bedste tip her er at gøre det til en andens opgave. Ofte er det en teknisk skribent, der ved, hvordan man taler til målgrupper med forskellige færdigheder, som kan oversætte udviklernes ord til brugbare punkter, og som overvåger rettidig vedligeholdelse og opdatering af dokumentationen. Men det er muligt at administrere god dokumentation selv uden en ekspert i dit personale. API-håndteringsværktøjer som Swagger UI, Spotlight, Apiary og værktøjer til specifikation af docs har en bred funktionalitet til at hjælpe dig med at lave docs, som udviklerne vil elske.