Teknisk dokumentasjon på kritisk sti

Techdocs-siten består av:

• Praktiske guides med mange kode-eksempler.
• Komplette, fungerende eksempler som kan sjekkes ut og kjøres selvstendig.
• Utfyllende API-dokumentasjon.

“Vi er jo begge utviklere, så vi lagde den dokumentasjonen vi selv skulle ønske vi hadde.”

– Christian

Vi tok mange grep for å sørge for at dokumentasjonen denne gangen skulle holde seg komplett og oppdatert.

• Kode-eksemplene i guidene hentes direkte fra de kjørende eksemplene. Dersom de kjørende eksemplene oppdateres i forbindelse med en endring, så vil oppdateringen automatisk også gjenspeiles i guiden.

• Eksempler på respons fra serveren for hvert endepunkt hentes inn i dokumentasjonen ved å utføre de faktiske kallene til en staging-server. Resultatet formateres og vaskes for sensitive data.

• Det blir generert kode-eksempler for bruk av hvert API-endepunkt, basert på informasjonen som hentes ut av applikasjonen.

“Når SPiD skulle legge til et SDK for Node.JS, var det snakk om en times arbeid å legge til hundrevis av eksempler på bruk av det nye SDKet.”

– Magnar

Nettstedet ble utviklet på nytt fra grunnen av. Ettersom vi skulle massere data hentet inn fra en rekke kilder valgte vi en tilnærming med funksjonell programmering med Clojure. Vi skulle generere en relativt stabil innholdsside, så det ga mening å lage statiske sider med Stasis og Optimus - teknologier vi kjente godt fra å lage Kodemakers egne nettsider.

Siden vi fikk lage nettstedet fra bunn av, var det naturlig å gjøre det med OOCSS. Da kostet det oss lite å også gjøre sidene responsive, slik at de fungerer godt både på nettbrett og mobil.

Vi valgte også en løsning der dokumentasjonen ikke ligger i en database på en server, men vedlikeholdes i Git. Utviklerne har nå muligheten til å løpende dokumentere det de lager – uten at det lager støy i den online dokumentasjonen. Kodebasen og dokumentasjonen kan følge samme branching-strategi og livssyklus.

Når Magnar ikke jobbet sammen med Christian, gikk det mye i å lage infrastrukturen rundt oppbygging av sidene. Målet var å gjøre det så lett som mulig å vedlikeholde dokumentasjonen. Han lagde også den responsive designen, og importrutinen for endepunkter.

Christian og Magnar jobbet mye sammen, og hadde begge fingerene i det meste. Når Christian jobbet alene brøytet han seg gjennom alle endepunktene i APIet, og beskrev alt som var - inkludert et hierarki av datatyper og datastrukturer i bruk. Han lagde systemet for å hente ut faktiske resultater fra staging-server til bruk som eksempler.

Nye endringer i den tekniske dokumentasjonen rulles ut kontinuerlig, slik at hver commit til techdocs-repoet gjenspeiles på nettstedet etter få minutter.

Det er et gammelt problem: Hvordan holder man dokumentasjonen oppdatert? Med Kodemakers hjelp har SPiD fått en moderne løsning på problemet.