Uppdraget
Syftet med uppdraget var att göra SaaS-bolagets egenutvecklade API lättillgängligt, både genom kvalitativ och pedagogisk dokumentation och genom att sätta upp en extern utvecklarportal. Målgruppen för dokumentationen var utvecklare som finns hos SaaS-bolaget, vilket arbetar enligt dogfooding-principen, liksom utvecklare hos bolagets kunder och partners.
“Vad vi behöver är ett API som är lätt att använda och enkelt att förstå. En utvecklare hos våra kunder ska snabbt kunna förstå och bedöma vårt API:s funktionalitet och börja använda det inom några minuter” säger bolagets produktägare.
Väldokumenterade API:er är även en förutsättning för att bolaget ska kunna skala upp sin verksamhet. I uppdraget ingick rådgivning som tillåter företaget att få till så mycket automation som möjligt, i en lösning med god sökbarhet som är enkel att underhålla.
Utmaningar och åtgärder
För att metodiskt dokumentera ett API krävs att den tekniska skribenten har kunskaper om mjukvara, agila processer och utveckling. Det är viktigt att både förstå behoven hos de som använder API:et, som att snabbt få en god förståelse för produkten.
SaaS-bolaget behövde en lösning som gör deras API lättillgängligt och samtidigt inte skapar löpande kostnader för underhåll. Dokumenteras uppgift var att ta fram och implementera en lösning som förenklar dokumentationsarbetet för SaaS-bolagets utvecklare, samt att förmedla kunskap om hur man dokumenterar och publicerar API-dokumentation.
Dokumenteras konsult arbetade agilt och i iterationer med regelbundna avstämningar. Uppdraget inleddes med en förstudie där nuläget, det vill säga dokumentation, arbetsmetoder, processer och verktyg, kartlades först. Intervjuer med både produktteamet och målgruppen genomfördes, för att skapa en tydlig målbild för vad som behövde uppnås. Därefter identifierades gapet mellan nuvarande läge och den önskade lösningen och en åtgärdsplan med uppskattad tidsåtgång för arbetet togs fram.
Resultat och kundnytta
Efter att analyserna var klara och kunden godkänt åtgärdsplanen, blev slutreslutatet följande leveranser:
• Docs-as-code
• Utvecklarportal med static site generator
• Style guide
• Snabbguide
Docs-as-code och utvecklarportal med static site generator
Med målet att utveckling och dokumentering ska gå hand i hand rekommenderade Dokumentera arbetssättet docs-as-code. Det innebär bland annat att samma verktyg som redan används av utvecklare, t.ex. testning, versionshantering med Git och förvaring i datakataloger (repositories), även används för dokumentation.
När dokumentationen skrivs i samma kodredigeringsprogram som utvecklarna redan använder kan företag spara både tid och pengar. Utvecklarna behöver inte byta miljö för att dokumentera och bolaget besparas inköp av system för dokumentationshantering. För att strukturera och publicera dokumentation på en utvecklarportal användes en static site generator (SSG). Förslag och val av SSG anpassades efter bolagets behov och arbetsprocesser.
Style guide
En style guide med tydliga instruktioner till utvecklarna om hur dokumentation och beskrivningar av API:er ska skrivas togs fram tillsammans med en process för att kontinuerligt dokumentera i takt med utvecklingen. Baserat på användarnas behov skapade vi en informationsarkitektur och dokumentation som snabbt och enkelt tillåter bolagets kunder att bekanta sig med en komplex produkt och dess tillhörande koncept. Vi rekommenderade verktyg med bra sökfunktion och versionshantering.
Snabbguide
En snabbguide med information, instruktioner och generiska kodexempel ger nybörjare ett snabbt sätt att förstå och börja använda bolagets API. Referenstexter med kortfattade och enhetliga beskrivningar till versionshanterad API-referenser, i kombination med handledande exempel, förenklar nu arbetet för företagets nuvarande kunder och utvecklare.
Kundnöjdhet och tillväxt
Dokumenteras mål är alltid att det ska vara lätt att använda din produkt. Lösningen med docs-as-code ger bolagets kunder tillgång till uppdaterad dokumentation i samband med releaser, vilket minskar antalet support-frågor över tid och i sin tur ger bättre förutsättningar för ett företag som vill skala upp att hålla nere kostnader för support.
Att på ett enkelt sätt skapa och underhålla en korrekt och lättillgänglig API-dokumentation gör det möjligt för IT-bolagets anställda, kunder och partners att arbeta tillsammans som ett team för att utveckla integrerade produkter och tjänster som ger ömsesidiga fördelar. “Vi är mycket nöjda med resultatet. Att veta vad som behöver dokumenteras och hur vi publicerar med minsta möjliga insats har givit oss en bra start för framtiden” säger bolagets produktägare.