Vad är API-dokumentation?
API (Application Programming Interface) är ett digitalt gränssnitt som används för att olika system ska kunna kommunicera med varandra. API-dokumentationen beskriver vilken data som kan hämtas från olika system och hur den skickas till andra berörda system.
Varför är API-dokumentation viktigt?
API:er används till integration mellan olika system. API-dokumentation tas fram för att kunna beskriva gränssnittet för andra apputvecklare som vill kunna integrera sina system med dina samt för att underlätta en bra implementering.
Sätt rätt person på rätt uppgift
API:er kan vara komplexa. I teorin kan det verka självklart att låta utvecklarna skriva dokumentationen men det ger sällan ett bra slutresultat. Att lyckas med API-dokumentation handlar inte bara om att de tekniska detaljerna är korrekta utan det är minst lika viktigt att dokumentationen är rätt strukturerad, målgruppsanpassad och enkel att ta till sig.
Det är inte helt ovanligt att det slarvas med dokumentationen av API:erna. Utvecklaren kanske varken upplever sig ha tiden eller ansvaret för att ta fram dokumentationen, än mindre kunskapen för att kunna göra det på korrekt sätt. Det är därför viktigt att säkerställa att någon faktiskt har ansvaret för att ta fram dokumentationen. Det kan vara en intern resurs, eller en extern teknisk skribent.
Fungerande samarbete blir avgörande
För att API-dokumentationen ska bli så bra som möjligt krävs ett kreativt samarbete mellan den tekniska skribenten och utvecklaren. Ju tidigare den tekniska skribenten kommer in i produktutvecklingen desto bättre blir förståelsen för hur allt hänger ihop.
Utvecklaren granskar och korrigerar materialet under uppdragets gång för att säkerställa kvaliteten på den färdigställda API-dokumentationen.
Lättillgängligt innehåll
Skriven med ett enkelt och klart språk blir API-dokumentationen tillgänglig för alla i målgruppen oavsett kunskapsnivå. Undvik därför att använda facktermer utan en förklaring. Förkortningar bör även skrivas fullt ut första gången de används.
Med en tydlig och konsekvent struktur blir det enklare att hitta relevant information och lättare förstå den. Dela upp långa textavsnitt på ett logiskt sätt med tydliga rubriker. Använd samma struktur genom hela dokumentationen så att mottagaren känner igen hur texten är uppbyggd.
Glöm inte att…
- regelbundet ersätta länkar i API-dokumentationen som slutat fungera.
- se till så att API-dokumentationen är sökbar så att det är enkelt att hitta den information man letar efter.
- använda riktiga kodexempel i dokumentationen. Bra textbeskrivningar är nyttiga men inget blir så tydligt som fungerande kod.
- ange detaljer och information om alla felmeddelanden som kan uppstå när man arbetar med API:et.
- hålla dokumentationen uppdaterad i de fall där gällande API:et förändras.
Sammanfattning
Välgjord API-dokumentation sparar användare många timmars dubbelarbete och frustration. För att lyckas måste man dock ha koll på behoven hos sin målgrupp. Dessutom måste man tänka igenom hur dokumentationen ska struktureras upp och skrivas för att den ska bli användbar för målgruppen. Genom att lämna över ansvaret till en erfaren teknisk skribent kan man säkra att arbetet blir gjort på ett bra sätt.