Documenteren vóór programmeren: mijn regel voor integraties die ik niet beheer

Een repository-viewer die ik afgelopen zomer maakte, heeft acht commits in zijn eerste week. De eerste vier raken geen enkele regel applicatie aan: het zijn de init vanuit mijn template en drie documentatiecommits. De vijfde is al de hele app.

Dat was geen discipline. Het was dat ik bij het schrijven van het document ontdekte dat mijn mentale model van de integratie fout was, en dat repareren in een .md kostte twintig minuten in plaats van twee dagen.

De fout van beginnen met code bij een externe integratie

Als de logica van jou is, is de code lezen de beste documentatie die bestaat. Als het van een externe API afhangt niet: wat je moet weten staat niet in jouw code en niet in de hunne. Het staat in de limieten, de quota en de deprecated parameters.

In die viewer haalde ik een tijdlang twee verbindingen met dezelfde provider door elkaar. De OAuth voor login en het servertoken om de API te lezen lijken hetzelfde en zijn dat niet. De één zorgt dat een mens binnenkomt, de ander dat de server leest. Ze falen anders. Dat in een document in twee secties opschrijven was wat me deed inzien dat een viewer van publieke repo's alleen de tweede nodig had.

Was ik met de code begonnen, dan had ik dat bij de derde 401 ontdekt.

Wat ik precies documenteer vóór de eerste regel

Ik documenteer niet het ontwerp van mijn app. Ik documenteer wat ik niet beheer. Concreet:

• De echte limieten, gemeten, niet geciteerd. Het is niet genoeg om "5.000 verzoeken per uur" van de website te kopiëren. Ik heb het aan het quota-endpoint gevraagd: 60/u zonder authenticatie, 5.000/u geauthenticeerd, 30/min bij zoeken. En ik heb gemeten dat een 304 Not Modified geen quota kost — 4972, 4972, 4972 met conditionals, en 4971 bij dezelfde aanroep zonder If-None-Match. Dat getal dat zich herhaalt is het centrale argument van het document, en zonder het uit te voeren heb je het niet.
• Wat niet te automatiseren is. De OAuth App maak je niet via de CLI: er is geen endpoint om hem aan te maken en geen om het client secret te lezen, dat maar één keer in de browser wordt getoond. Het is een handmatige stap, en de dag dat je de omgeving opnieuw opzet, ben je hem vergeten.
• De plafonds die je in productie verrassen. 2.000 tokencreaties per uur, wat een plafond op logins is, niet op verzoeken. En geforceerde herautorisatie als een gebruiker tien keer in een uur binnenkomt. Geen van beide duikt op als je het happy path leest.
• Wat de beslissing NIET oplost. Ik noteerde dat login verplichten de noodzaak van conditionele caching niet wegneemt, omdat de bucket van de gebruiker wordt gedeeld met zijn PAT en met andere apps die namens hem handelen. Als je dat niet opschrijft, geeft de beslissing je een vals gevoel van zekerheid.

Niets hiervan is een kwestie van mening. Het zijn feiten die je ofwel controleert ofwel verzint.

De cookbooks: elk onderdeel geïsoleerd testen voordat je het integreert

In een AI-dienst voor documentanalyse deed ik hetzelfde op een andere manier. Voordat er ook maar één onderdeel de dienst in ging, had elk onderdeel een cookbook: een script dat het alleen uitvoert, zijn uitvoer naar een map schrijft en zich registreert in een run_all_cookbooks. PDF-parser, chunker, embeddings, getallendetector, verifieerbare extractie. Eén per onderdeel.

De waarde is niet de test. De waarde is dat wanneer de uitvoer van de chunker van vorm verandert, je dat ziet in een tekstbestand in plaats van in een fout drie lagen hoger. Bij het omzetten van de pipeline naar asynchroon werden de cookbooks runners met asyncio.run en gebeurde de migratie stuk voor stuk, niet in één klap.

De prijs is dat je ze moet verwijderen als ze niet meer kloppen. Maanden later staat er een commit die de verouderde cookbooks weghaalt. Een cookbook dat niet meer bij het onderdeel hoort is erger dan geen cookbook.

Documentatie als bron van waarheid om later te auditen

In een galerij van UI-concepten schreef ik eerst een ontwerprichtlijn voor het onderdeel — maten, spacingladder, grijsschaal, welke primitive waarvoor wordt gebruikt — en daarna auditte ik de code daartegen.

Het interessante is dat de audit de richtlijn corrigeerde, niet alleen de code. Drie dingen die de .md te weinig zei: dat het begeleidende grijs in vijf stappen loopt en niet in twee; dat de spacingladder vier treden heeft en geen drie, want hem drie noemen maakte van zes legitieme toepassingen afwijkingen; en dat de drie dialogen in werkelijkheid dezelfde dialoog zijn, met dezelfde box en dezelfde header, en dat de correctie door het niet te zeggen maar op één ervan was toegepast.

Zonder voorafgaand document bestaan die drie bevindingen niet. Je hebt niets om tegen af te zetten en alles wat je vindt is "ik vind dat".

Wanneer dit tijdverspilling is

Het criterium dat ik gebruik:

• Als de integratie van begin tot eind van jou is, documenteer dan niet vooraf. De code is de waarheid en het document veroudert.
• Als het een prototype is dat je weggooit, ook niet. Een spel dat ik in een dag schreef heeft niets op papier en dat is prima zo.
• Als het document gaat herhalen wat de officiële referentie zegt, schrijf het dan niet. Het draagt alleen bij als het jouw metingen, jouw versies en de valkuilen bevat die jou zijn overkomen.

En er is een fout die me duur kwam te staan: het document dat je vooraf schrijft, draagt jouw aannames in zich mee. In die viewer beschreef de hostingsectie een serverless platform omdat ik dat bij het opstellen van de opdracht als vanzelfsprekend aannam, niet omdat iemand het had besloten. Toen ik het corrigeerde naar een langlevende container, veranderde de hele conclusie: op serverless paste de agents-SDK niet; in een worker met een limiet van vijftien minuten per verzoek wel.

Daarom is de volgende stap niet optioneel. Er is een commit wiens enige taak is het document te verifiëren tegen levende bronnen: de query uitvoeren die in de gids staat, een ongeldige API-versie sturen zodat de API zelf de geldige opsomt, controleren dat per_page=500 stilzwijgend wordt teruggebracht tot 100, het snippet typen dat niet compileerde in strikte modus. Die commit ontdekte dat 18 van de 20 teruggegeven "issues" in werkelijkheid pull requests waren.

Een niet-geverifieerd document is een aanname in een mooi jasje. Een geverifieerd document is het enige deel van de integratie dat je over zes maanden niet zal voorliegen.