🎲 — mikrobloggeriet olorm — olorm-33 · olorm-34 · olorm-35

Trenger vi dokumentasjon?

Jeg kom akkurat ut fra nok et møte om en løsning som har integrasjon mot to tredjeparter.

Begge har vi eksisterende integrasjoner mot, men nå skal vi buke noe ny data, noen nye parametre, og ny versjon av noen endepunkt.

Jeg synes det er utfordrende at det er lite og mangelfull dokumentasjon.

Hva betyr egentlig feltet nId i respons-dataen? Er feltet externalX alltid satt, eller kun for noen typer?

Noe av dette er dokumentert på side 13 av et arbeidsdokument fra i fjor. Annet er “dokumentert” i et svar i en av hundrevis av Slack-tråder.

“Alle” misliker å skrive og oppdatere dokumentasjon, og alle hater utdatert og misvisende dokumentasjon.

“Koden er dokumentasjonen,” sies det. Den er aldri utdatert(?). Men for tredjeparts APIer har vi ikke koden, vi har bare stikkprøver av data og gjetninger.

Så jeg vi si: ja, vi trenger dokumentasjon.

Jeg tror vi hadde spart mange møter, duplikate Slack- og epost-spørsmål hvis vi hadde det. Hvis ikke tredjeparten leverer dokumentasjon, kanskje vi skulle dokumentert APIet på vår side, som best vi kan.

—Richard Tingstad