Leestijd: 9 minuten
API’s laten de wereld draaien. Ontwikkelaars gebruiken API’s bijna elke dag – volgens sommige schattingen besteden ze meer dan 10 uur per week aan het werken met API’s. Dit omvat niet alleen het gebruik ervan, maar ook onderzoek, googlen voor ondersteuning, het bestuderen van reviews, en natuurlijk, rondsnuffelen in de documentatie. Hoe duidelijk, gemakkelijk, nuttig en ondersteund uw API is, bepaalt de hele ervaring van de ontwikkelaar (DX) – een emotionele reactie die ontwikkelaars hebben op het product. In de API-economie is een goede ervaring voor ontwikkelaars van fundamenteel belang. API’s die ontwikkelaars helpen succesvol te zijn en een plezier zijn om te gebruiken, zullen veel gebruikers krijgen en boven de concurrentie uitstijgen. En dat begint al op het moment dat ze de documentatie voor de eerste keer openen.
Bekijk deze video voor een inleiding tot de API-technologie
Vandaag gaan we het hebben over hoe we een positieve ervaring voor ontwikkelaars in de API-documentatie kunnen bevorderen. Maar eerst moeten we begrijpen wat slechte API-documenten maakt.
Wat ontwikkelaars haten in API-documentatie
De dev-gemeenschap is een gepassioneerde gemeenschap. Het is specifiek gepassioneerd over de dingen die ze niet leuk vinden. Als ze een API niet goed vinden, is dat meestal vanwege de slechte documentatie, zelfs als het product eigenlijk geweldig is. Hier zijn enkele veel voorkomende problemen die devs hebben met API-docs.
Het is niet geschreven in eenvoudige mensentaal. Dit is een veelvoorkomend probleem voor automatisch gegenereerde docs of docs die door de makers worden verwaarloosd. Hoewel veel hulpmiddelen voor het genereren van documentatie goed werk doen met het becommentariëren van de code, kunnen ze de werkelijke uitleg in het Engels, geschreven door een ontwikkelaar of technisch schrijver, niet vervangen.
Het heeft zeer weinig codevoorbeelden. Dit is een andere kant van het spectrum waar de uitleg overvloedig is, maar er zijn minimale voorbeelden van de eigenlijke code.
Het is alleen beschikbaar voor geregistreerde gebruikers. Deze niet-zo-slimme manoeuvre doet niets voor uw marketing. Het frustreert alleen de mensen die willen weten wat uw API doet voordat ze beslissen of ze hem willen (zoals ieder weldenkend mens zou doen).
Het is te lang/kan niet worden gevonden/onjuist/is al jaren niet bijgewerkt, enz. Het maken van goede docs is bijna net zo belangrijk als het bouwen van een goede API. Want slecht geschreven documenten of documenten die niet gevonden kunnen worden door simpelweg te googlen op “Product API” zijn een mislukking voor de hele ontwikkeling. Als je geïnteresseerd bent, hebben we al specifieke kenmerken van technische documentatie in het algemeen geschetst. Maar API docs verdienen een apart artikel. Hoe schrijf je nu goede API-documenten?
Streef naar spec-gedreven ontwikkeling
Spec-gedreven ontwikkeling (SDD) is vergelijkbaar met test-gedreven ontwikkeling, waarbij je voor elke functie testgevallen schrijft en vervolgens code schrijft die deze moet doorstaan. Bij SDD maak je documenten, of op zijn minst enkele delen daarvan, parallel aan het bouwen van een API, vaak volgens een bepaald API-beschrijvingsformaat dat een specificatie wordt genoemd.
Een API-specificatie is als een sjabloon van je toekomstige documenten, de uniforme taal die het ontwerp van je API beschrijft, uitlegt hoe het functioneert en wat je ervan kunt verwachten. Er zijn een paar specificaties, zoals RAML (RESTful API Modeling Language), OpenAPI (voorheen Swagger), en API Blueprint, maar er is een trend gaande om alle specs te combineren onder de motorkap van OpenAPI.
Deze specs hebben voorgebouwde documentatie tools die het mogelijk maken voor het schrijven en beheren van je docs. API Console genereert bijvoorbeeld automatisch documenten van RAML- en OpenAPI-indelingen en helpt u deze op uw bestaande webapplicatie of als zelfstandige app uit te voeren.
API Console laat u een webportaal bouwen voor uw API-documenten van RAML- en OpenAPI-specificaties
Bron: Pawel Psztyc
Alternatief voor traditionele API doc oplossingen zoals WordPress of Drupal CMS’en, API spec producten zijn open source, gemaakt door de dev gemeenschap voor de dev gemeenschap, hebben parsers in verschillende programmeertalen, en constante creator support.
Schrijf voor het instapniveau
Er is een reden waarom technische documentatie meestal niet door ontwikkelaars zelf wordt geschreven – het is de taak van technische schrijvers, experts in het vertalen van technische aspecten naar een leesbaar formaat. Maar zelfs technisch schrijvers hebben de neiging een beetje jargon in de tekst te laten lekken.
Een API zoals elk softwareproduct wordt gemaakt voor een specifiek publiek. Maar het publiek voor documentatie is groot. Er zijn drie hoofdgroepen van gebruikers van documentatie:
- ontwikkelaars die een nauwe interactie met de docs zullen hebben
- beslissers zoals CTO’s en oplossingsarchitecten die snel willen bepalen of uw API een goede pasvorm zal zijn
- waarnemers zoals journalisten, tech-schrijvers, en zelfs concurrenten die uw API niet noodzakelijkerwijs ooit zullen gebruiken.
En zelfs binnen elk van deze groepen zijn er mensen met verschillende vaardigheden, rollen en behoeften, en ze moeten allemaal een positieve ervaring met de docs hebben. Hoe richt je je op hen allemaal? Door je te richten op de minst ervaren gebruikers. Dus, hoe schrijf je documenten voor een nieuwkomer?
Start met de mogelijkheden in plaats van met de technische details. Begroet gebruikers met een boeiend verhaal over hoe uw API hun product kan verrijken of het leven van ontwikkelaars tien keer eenvoudiger kan maken.
Amazon Alexa API-documenten beginnen met uit te leggen wat Alexa doet en welk voordeel het de klant kan opleveren
Laat zien waar je moet beginnen. API-docs zijn berucht omdat ze te overweldigend zijn en ervan uitgaan dat gebruikers ruime ervaring met API’s hebben. De ‘getting started’-sectie is verplicht, en moet worden geschreven met geduld voor een potentiële gebruiker.
Facebook biedt een duidelijke referentie voor beginners en volgt het ‘getting started’-proces stap voor stap
Maak instructies voor de meest voorkomende use-cases. U weet waarschijnlijk al voor welke functies mensen uw API gebruiken. Maak aparte secties waarin ze aan bod komen en neem daar voorbeeldberichten in op.
Gebruik een gemoedelijke toon. De ontwikkelaarsgemeenschap is ontspannen en informeel, dus ze zullen droge bedrijfstaal niet waarderen, ook al klinkt het “professioneler”. Goede docs praten altijd met mensen.
Educate on external tools. Als je API het gebruik en begrip vereist van producten en concepten van derden, zoals OAuth of npm, neem dan links op naar docs of installatiegidsen.
Maak het makkelijk om te leren. API-documenten zijn geen IKEA montage-instructies, ze zijn de leerbron. Verrijk uw documentatie met FAQ’s, tutorials, blogs en zelfs video’s wanneer mogelijk.
Integreer must-have secties
In 2019 heeft SmartBear, de ontwikkelaar van Swagger, API-ontwikkelaars en -gebruikers ondervraagd. Ze vonden welke docs-kenmerken het belangrijkst worden geacht in de gemeenschap, waardoor we een lijst hebben van de must-have documentatiesecties die devs willen dekken. We nemen er een paar door.
SmartBear heeft 3.000 API-gebruikers ondervraagd
Examples. Voorbeelden worden meestal gepresenteerd als stukjes code. Die zijn nuttig genoeg, maar kunnen nog praktischer worden gemaakt. Bijvoorbeeld door een transcript van velden op te nemen zoals in Medium docs of zelfs door een mock API te maken die ontwikkelaars kunnen testen en gebruiken door echte calls te maken. Mock API’s kunnen eenvoudig worden gedeeld via een URL of op GitHub, en als dat tot een bepaald detailniveau gebeurt, zelfs worden gebruikt in het eindproduct.
Status en fouten. Er zijn standaard status codes en die specifiek zijn voor uw API. Het is een goed idee om alle fouten op te nemen die door uw API kunnen worden veroorzaakt. Fouten worden vaak op een speciale pagina van de docs gezet, maar het is zinvol om sommige ervan direct onder het endpoint te dupliceren waar ze het meest aan de oppervlakte komen.
Authenticatie. De meeste API-docs beginnen met authenticatie en autorisatie. Het zou info moeten bevatten over hoe een API sleutel te krijgen en hoe verzoeken te authenticeren, inclusief mogelijke fouten, token verval tijden, en een uitleg over authenticatie gevoeligheid (in principe eraan herinneren dat sleutels niet kunnen worden gedeeld, en waar ze kunnen worden gebruikt).
HTTP verzoeken. Het verstrekken van web requests in HTTP is het absolute minimum voor documentatie. Meestal wordt aangenomen dat ontwikkelaars weten hoe ze HTTP requests moeten versturen in de taal van hun keuze, maar soms voegen API-makers requests in verschillende talen toe. Dit kan automatisch worden gedaan via API spec tools en API management tools zoals Postman.
Gebruik industrie-standaard lay-out
Als je een documentatie generator gebruikt, is de lay-out al voor je bepaald. De meeste API-documenten zien er hetzelfde uit en voelen hetzelfde aan. Als je er een paar hebt gebruikt, weet je hoe je nieuwe docs moet benaderen. Toch is het organiseren van grote hoeveelheden data, het vindbaar en gemakkelijk navigeerbaar maken een complexe taak. Hier zijn enkele kenmerken van de meest functionele lay-out.
Dynamische lay-out. U kunt een verouderde API herkennen aan de statische documentatie. Een enkele pagina of zelfs een PDF-document is niet meer genoeg in 2020. Dynamische documenten zijn gemakkelijk door te kijken, bij te werken en te bookmarken.
Sticky inhoud. Nee, de navigatiebalk leidt niet af en steelt geen kostbare schermruimte. Houd de inhoud altijd in het zicht.
Driekolomsindeling. Niet vaak gebruikt, deze lay-out maakt het mogelijk om nog een kolom aan de rechterkant te hebben voor de codevoorbeelden. Dit is natuurlijk alleen zinvol als u veel tekst hebt en de code wilt markeren zodat gebruikers niet heen en weer hoeven te scrollen of tussen tabbladen hoeven te schakelen.
HubSpot API-documenten gebruiken een driekolomsindeling
Gebruik contrasterende kleuren voor syntaxis. Ontwikkelaars besteden veel tijd aan het bekijken van uw codevoorbeelden, dus maak ze leesbaar en scheid verschillende componenten door kleuren.
Dit voorbeeld uit de Graph API-docs van Facebook laat ook zien hoe u verschillende tabbladen kunt gebruiken om te kiezen tussen SDK’s
Opgeslagen scroll-status. Dit is een klein detail dat elke ontwikkelaar zal waarderen. U kunt ook ankerlinks gebruiken om verschillende secties van de pagina aan te geven voor het geval ze de URL kopiëren.
Moedig feedback aan. Uw documenten zijn uw belangrijkste marketinginstrument – als mensen ervan houden, zullen ze uw API eerder gebruiken dan die van de concurrent en de gemeenschap eromheen stimuleren. De gebruikelijke “Was deze pagina nuttig?”-boodschap laat u weten hoe goed u de vragen van devs beantwoordt en het feedbackformulier zal vaak worden gebruikt zolang u het waarmaakt.
Ga niet weg van uw docs
Verouderde docs is de grootste ergernis van API-gebruikers. Het is ook een van de meest gemaakte fouten. Ontwikkelaars schrijven vaak over updates enkele dagen nadat ze zijn uitgerold, soms beperken ze zich tot een paar zinnen. Dit gebeurt omdat er geen vast proces is voor docs updates en het is niemands verantwoordelijkheid. Hier is hoe u kunt zorgen voor regelmatige en nuttige doc-updates.
Voorbereid docs voorafgaand aan de updates. Maak er een extra stap van in je lanceerplan, rol ze niet uit voordat je goed geschreven, gedetailleerde en geredigeerde paragrafen hebt om je updates te introduceren.
Verwijder regelmatig deprecated data. De documenten moeten vaak worden herzien, ten minste eens in de paar maanden. Met behulp van feedback van gebruikers kun je inconsistenties eerder opmerken en er moet altijd een teamlid verantwoordelijk zijn voor het beoordelen ervan en het reageren op updates.
Gebruik analytics om docs te verbeteren. Standaard API-analyses vertellen je welke endpoints het vaakst worden gebruikt, zodat je je op bepaalde delen van de documentatie kunt richten en meer nuttige informatie kunt bieden of speciale tutorials kunt maken. Monitor de use-cases waarvoor uw API’s worden gebruikt, want daarmee kunt u de waardepropositie verbreden en de docs bijwerken met meer mogelijkheden.
Grote API-documentatievoorbeelden
Er zijn tonnen goede docs om te verkennen en van te leren. In aanvulling op de voorbeelden die we in het hele artikel hebben gedeeld, zijn hier nog enkele voorbeelden voor u om van te genieten en kennis te nemen.
Medium API-documentatie
Medium API-documenten houden zich niet noodzakelijkerwijs aan alle regels die we vandaag hebben opgesomd, maar ze zijn geweldig voor de beperkte functionaliteit die deze API ondersteunt – het plaatsen en doorzoeken van publicaties op Medium. Ze worden gedeeld op GitHub, hebben echt een korte maar duidelijke inhoud met tonnen voorbeelden, elk eindigend met een transcript van alle parameters die in de code worden genoemd, inclusief mogelijke fouten. Het is opmerkelijk eenvoudig, maar betrouwbaar – alle suggesties kunnen direct op GitHub worden gedaan en de docs worden regelmatig bijgewerkt.
Mailchimp API-documentatie
Mailchimp realiseert zich dat het grootste deel van zijn publiek bestaat uit marketingprofessionals en gebruikt taal die zelfs niet-techneuten in staat stelt om te begrijpen hoe ze met zijn API’s moeten werken. In een oogopslag volgt elke sectie dezelfde structuur:
- wat een eindpunt doet en wat de gids gebruikers laat doen
- wat je nodig hebt – eventuele toegangen of accounts die een gebruiker eerst moet krijgen
- wat elke functie is met een tekstbeschrijving, een codevoorbeeld in verschillende talen, en soms screenshots van de interface.
Er is zelfs een kopieerknop voor elk stukje code – een detail dat niet-techneuten zeker zullen waarderen.
Twilio API-documentatie
Twilio heeft befaamd goede API-docs. Hoewel de docs slechts het topje van de ijsberg zijn van alle hulp die Twilio biedt – er zijn SDK’s in verschillende talen en voorbeeld-apps voor iOS, Android en het web. In de eerste plaats volgen ze de driekoloms logica met de code direct rechts van de gids. De eenvoudigste acties worden in detail uitgelegd met veel links voor aanvullende informatie en screenshots. Feedback wordt ook aangemoedigd via een “Beoordeel deze pagina”-knop en links naar het ondersteuningsteam en de tag op StackOverflow.
Spotify API-documentatie
Hoewel de web-API-docs van Spotify erg typisch zijn, hebben ze veel extra informatie in hun Spotify for Developers-platform. Er zijn demo’s voor basisfuncties, mock apps, live voorbeelden gebouwd met behulp van Spotify API’s en widgets, wrappers voor verschillende programmeertalen, en natuurlijk, de console. De console is in feite een interactieve documentatie waar je jouw (of voorbeeld) gegevens in kunt vullen en endpoints live kunt verkennen. Krachtige producten in combinatie met een sterke kennisbank maken Spotify tot een betrouwbare partner waar ontwikkelaars graag mee samenwerken.
Behandel docs met zorg
Documentatie is het enige contactpunt dat je met het grootste deel van je publiek hebt, dus je moet leren om er duidelijk mee te communiceren. De beste tip hier is om het iemands taak te maken. Vaak is dit een technisch schrijver die weet hoe hij een publiek met verschillende vaardigheden moet aanspreken, die de woorden van ontwikkelaars kan vertalen in bruikbare punten, die toeziet op het tijdig onderhouden en bijwerken van de docs. Maar het beheren van goede documentatie is mogelijk, zelfs zonder een expert in je staf. API-beheertools zoals Swagger UI, Spotlight, Apiary en docspecificatiehulpmiddelen hebben een brede functionaliteit om u te helpen docs te maken waar ontwikkelaars van zullen houden.