Claes Bergsten, Tech Lead Payment, Schibsted Payment ID

«Sammen med Kodemaker ønsket vi å øke kvaliteten på vår tekniske utviklerdokumentasjon. Vi ønsket et penere, mer responsivt uttrykk og hvis mulig å automatisere deler av prosessen. Prosjektet hadde ingen føringer på teknologi eller verktøy og Kodemaker var fra første dag en proaktiv partner som hjalp til å forme løsningen. Vi opplevde konsulentene som svært faglig dyktige og de ble fort en del av gjengen her. De hadde ingen problemer med å sette seg inn i våre problemstillinger og vi endte med en løsning som leverte mer enn vi i utgangpunktet hadde ambisjoner om å få til.»

Claes Bergsten

Tech Lead Payment, Schibsted Payment ID
+47 916 68 984

Teknisk dokumentasjon på kritisk sti

Schibsted Payment ID (SPiD) håndterer innlogging og betaling for FINN.no, VG, Aftenposten, Dine Penger og Aftonbladet. I tillegg til disse store selskapene, ønsker SPiD å kunne tilby sine tjenester også til mindre bedrifter.

SPiD så at nye integrasjoner var vanskelige for nye kunder å gjennomføre uten å lene seg tungt på SPiD sine utviklingsteam. Den tekniske dokumentasjonen var utdatert og mangelfull. Resultatet var at de ikke kunne rulle ut til så mange kunder som de hadde ønsket. Det var i denne sammenheng at Kodemaker ble kontaktet.

SPiD Techdocs

To Kodemakere i team leverte i 2014 et dedikert nettsted for teknisk dokumentasjon. Utviklingen foregikk hos SPiD over en 6 måneders periode.

2 Kodemakere

950 timer / 02.2014-08.2014

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

Levende dokumentasjon

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

Et case for funksjonell programmering

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.

Magnar Sveen

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.

Systemutvikler
+47 918 56 425
magnar@kodemaker.no

Christian Johansen

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.

Systemutvikler
+47 934 17 480
christian@kodemaker.no

En ny løsning på et gammelt problem

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.