Evergreen Notes: Schrijf notities die in de loop van de tijd aan waarde winnen

De meeste engineeringnotities worden één keer geschreven en daarna vergeten. Je vastlegt iets tijdens een debugsessie, plakt het ergens en vind het twee jaar later zonder context waarom het destijds belangrijk was.

Het probleem ligt niet in de inzet. Engineers schrijven constant — code-opmerkingen, Slack-berichten, Confluence-pagina’s, Jira-beschrijvingen, pull request-toelichtingen, architectuurschema’s. Het probleem is dat de meeste van die notities geschreven zijn voor een specifiek moment en slecht verouderen. Ze composteren niet. Ze hopen zich op.

Evergreen notities zijn het alternatief. Het idee is eenvoudig: schrijf elke notitie zo dat deze onbeperkt nuttig blijft, verbetert wanneer je hem opnieuw bezoekt en op een manier met andere notities verbindt waardoor het hele systeem met de tijd waardevoller wordt.

De term werd populair gemaakt door onderzoeker Andy Matuschak, wiens eigen openbare notities het idee op grote schaal demonstreren. Voor engineers heeft het principe directe toepassingen in technisch schrijven, documentatie, architectuurkeuzes en het langetermijnvastleggen van hardverworpen lessen.

Wat maakt een notitie evergreen

Atomaar

Een evergreen notitie bevat één idee. Niet één onderwerp — één idee.

Een notitie genaamd “PostgreSQL” is niet evergreen. Het is een container die wacht om gevuld te worden. Een notitie genaamd “Partiële indexes verminderen schrijfoverhead wanneer queries gericht zijn op een klein subset” is evergreen. Het stelt een specifieke, draagbare bewering.

De atomaire beperking is belangrijk omdat het hergebruik regelt. Een container-notitie kan alleen worden gelinkt als een vaag onderwerp. Een atomaire notitie kan worden gelinkt waar ook maar dat specifieke idee van toepassing is — in een discussie over query-optimalisatie, in een vergelijking van indexstrategieën, in een projectnotitie over een specifiek prestatieprobleem.

Zelfstandig

Een evergreen notitie moet begrijpelijk zijn zonder zijn oorspronkelijke bron.

Dat betekent schrijven in je eigen woorden. Een notitie die zegt “Zie het gelinkte artikel — goede stuff over caching” is niet evergreen. Een notitie die zegt “Write-through caching updatet de cache synchronis met de database bij elke schrijfoperatie, wat leesconsistentie verbetert ten koste van hogere schrijflatentie” is evergreen. Je kunt het een jaar later lezen zonder de oorspronkelijke bron na te jagen.

Dit is moeilijker dan het klinkt. Het schrijven van een zelfstandige notitie vereist dat je werkelijk begrijpt wat je leest, niet alleen dat je het markeert. Die verwerkingsstap is waar het meeste leren plaatsvindt.

Evoluerend

Evergreen notities verbeteren met de tijd in plaats van te verouderen.

Een vluchtige notitie heeft een levenscyclus: je schrijft hem, hij dient een moment, hij wordt irrelevant. Een evergreen notitie zou de moeite waard moeten zijn om zes maanden of twee jaar later opnieuw te bezoeken en te verfijnen. Je kunt een tegenvoorbeeld toevoegen, het updaten met een productie-ervaring, het linken aan een nieuw patroon, of het simpelweg preciezer herschrijven.

Het woord “evergreen” is intentioneel: deze notities sterven niet na de oogst. Ze blijven bestaan en verbeteren.

Gekoppeld

Evergreen notities verbinden zich met andere notities in plaats van geïsoleerd te zitten.

Een zelfstandige notitie over write-through caching verbindt zich natuurlijk met notities over lees-intensieve werklasten, cache-onttrekking, eventuele consistentie en databaseschrijfprestaties. Elke link maakt beide notities nuttiger — de verbinding oppert context die geen van beide notities alleen bevat.

De gewoonte om te linken is wat een verzameling van individuele inzichten omzet in een netwerk van verbonden begrip.

Notitietypen en wanneer je elk moet gebruiken

Het begrijpen van evergreen notities vereist het begrijpen van wat ze niet zijn.

Vluchtige notities zijn tijdelijke vastleggingen. Een regel geschreven tijdens een debugsessie, een bladwijzer om opnieuw te bezoeken, een vraag om op te volgen. Vluchtige notities dienen een moment. Ze moeten snel worden verwerkt en ofwel worden weggegooid of gepromoveerd naar iets duurzaams. De meeste vluchtige notities worden nooit evergreen notities, en dat is prima.

Literatuur notities zijn samenvattingen van externe bronnen — een documentatiepagina, een postmortem, een hoofdstuk uit een boek, een conferentiepraatje. Literatuur notities bewaren wat een bron zei. Ze zijn een stap naar begrip, niet het begrip zelf. Een literatuur notitie zegt “deze bron beweert X.” Een evergreen notitie zegt “Ik geloof X om deze redenen.”

Evergreen notities synthetiseren wat je bent gaan begrijpen. Ze leven aan de output van het leerproces, niet aan de input.

Evergreen technische notities schrijven

De structuur van een goede evergreen technische notitie volgt een eenvoudige logica: bewering, bewijs, implicatie.

# Write-through caching verbetert leesconsistentie ten koste van schrijflatentie

Write-through caching updatet de cache tegelijkertijd met de onderliggende opslag
bij elke schrijfoperatie. Elke leesoperatie raakt verse data omdat de schrijfpad
consistentie waarborgt voordat de schrijfoperatie wordt bevestigd.

De afweging is schrijflatentie — elke schrijfoperatie vereist nu twee operaties (opslag
en cache) om te voltooien voordat de aanroeper een bevestiging ontvangt.

Dit patroon is geschikt voor lees-intensieve werklasten waar cache-veroudering een echte
zakelijke impact heeft, zoals productvoorraadtelers of gebruikersinstellingen.

Links:
- [[Read-through caching verschuift cache-populatie naar leestijd]]
- [[Cache-onttrekking is een coördinatieprobleem]]
- [[Write-behind caching wisselt consistentie in voor schrijfthroughput]]

Die notitie is nuttig zonder de bron. Het stelt de bewering, verklaart de afweging, geeft een context waar het van toepassing is en linkt naar gerelateerde ideeën.

Wat te vermijden

Tijdsgebonden referenties verouderen slecht. “Per Postgres 14 werkt dit gedrag zo” is een literatuur notitie, geen evergreen notitie. Schrijf het principe in plaats daarvan: “De planner overslaat index scans wanneer de geschatte rijtel een drempel overschrijdt ten opzichte van de tabelgrootte.” Die bewering overleeft versie-wijzigingen zelfs als de drempel verandert.

Tool-specifieke commando’s zonder context zijn snippets, geen notities. Een notitie die slechts een kubectl commando is gekopieerd van een StackOverflow antwoord is niet evergreen. Een notitie over waarom dat commando werkt — welke Kubernetes resource het beïnvloedt en welk probleem het oplost — heeft een kans.

Aannames over de kennis van de lezer degraderen snel. Schrijf alsof je uitlegt aan een competente collega die niet in je huidige context zit.

Goede kandidaten voor evergreen notities in engineering

Bijna elke hardverworpen les met brede toepasbaarheid is een goede kandidaat:

• Architectuurafwegingen en de redenering achter keuzes
• Debugpatronen die van toepassing zijn op verschillende systemen
• API-ontwerp regels en hun uiterste gevallen
• Prestatiekarakteristieken met daadwerkelijke cijfers
• Beveiligingsaannames die bleken fout te zijn
• Teststrategie lessen van projecten waar de aanpak faalde
• Implementatiebeperkingen die veranderden hoe het team werkte

De gemeenschappelijke draad: specifiek genoeg om uitvoerbaar te zijn, algemeen genoeg om meer dan één keer van toepassing te zijn.

De evergreen workflow

Stap 1: Vluchtige notities vastleggen

Leg snel vast zonder te veel na te denken. Het doel is niet om op dat moment een evergreen notitie te produceren — het is om het ruwe materiaal voor één te behouden.

Tijdens een debugsessie:

Ontdekte dat de cache verouderde gebruikersrechten terugleverde na rolwijzigingen.
De TTL was 5 minuten maar de rolupdate was onmiddellijk.
Moet nadenken over hoe dit af te handelen — ontrekking bij schrijven?
Of kortere TTL? Of gebeurtenis-gedreven update?

Dat is een vluchtige notitie. Het is geen evergreen notitie, maar het bevat de kiemen van meerdere.

Stap 2: Verwerken naar evergreen notities binnen 48 uur

Verwerking is waar de waarde verschijnt. Neem de ruwe vastlegging en extract de ideeën die het waard zijn om te behouden.

Van die debugnotitie zou je kunnen schrijven:

# Rolgebaseerde cache-ingangen vereisen ontrekking bij schrijven, niet alleen TTL-verlopen

Wanneer gecachte data rechten of rollen codeert, is TTL-gebaseerd verlopen niet veilig.
Een gebruiker wiens rol wordt gedegradeerd behoudt verhoogde rechten tot de TTL verloopt.
Schrijftijd-onttrekking — of gebeurtenis-gedreven cache-updates bij rolwijziging — is vereist
voor correctheid in rechtensensitieve caches.

Links:
- [[Cache-onttrekking is een coördinatieprobleem]]
- [[Autorisatiebeslissingen mogen niet worden gecached in rust zonder validatie]]

De debugcontext is weg. Het draagbare idee blijft.

Stap 3: Verbinden met bestaande notities

Na het schrijven van de notitie, besteed twee minuten aan het volgende:

• Welke bestaande notitie heeft hier een relatie mee?
• Welk concept is hier afhankelijk van?
• Wat verlengt of tegenspreekt dit?

Voeg links toe in beide richtingen. De nieuwe notitie linkt naar bestaande notities. Bestaande notities die nu rijker zijn door de verbinding linken terug.

Stap 4: Opnieuw bezoeken en verbeteren

Evergreen notities hebben geen enkele correcte staat. Elke keer dat je het idee opnieuw tegenkomt — in een productieincident, een ontwerprichtlijn, een code review-opmerking — overweeg dan om terug te keren naar de notitie en hem beter te maken.

Je zou kunnen:

• Een concreter voorbeeld toevoegen
• De bewering updaten op basis van nieuw bewijs
• Een voorbehoud verwijderen dat bleek niet te matteren
• Een link toevoegen naar een nieuwe gerelateerde notitie
• De openingszin herschrijven voor duidelijkheid

Die cyclus van verfijning is wat notities maakt tot composteren in plaats van vervaagen.

Evergreen notities en documentatie

Er is een nuttig onderscheid tussen persoonlijke evergreen notities en teamdocumentatie.

Persoonlijke evergreen notities zijn jouw begrip, geschreven voor het toekomstige jou. Ze kunnen ruw, opiniënt en onvolledig zijn. Hun waarde ligt in het herbruikbaar zijn voor je denken.

Teamdocumentatie is voor gedeeld begrip. Het vereist nauwkeurigheid, toegankelijkheid en eigenaarschap van onderhoud.

De twee lagen complementeren elkaar. Je evergreen notities over waarom een systeem op een bepaalde manier is ontworpen kunnen de ruwe materialen worden voor het architectuurbeslisregister. Je debugnotities kunnen het runbook voeden. Je API-ontwerp notities kunnen de stijlgids informeren.

De richting van de stroom is meestal: evergreen notities → gepolijste documentatie, niet omgekeerd.

Evergreen notities en RAG-systemen

Naarmate AI-geaugmenteerde kennishulpmiddelen praktischer worden, worden goed geschreven evergreen notities steeds waardevoller als bronmateriaal voor ophaling. Het ophalen versus representatie probleem in kennismanagement gaat essentieel over de kwaliteit van bronmateriaal — en evergreen notities, being atoom, zelfstandig en geschreven voor begrip, chunken goed voor vectorzoektochten.

Een Zettelkasten van atome evergreen notities is een natuurlijke basis voor een persoonlijk RAG systeem. De atome structuur aligneert met de ophaling chunkgrootte. De zelfstandige eigenschap betekent dat opgehaalde notities geen extra context nodig hebben om nuttig te zijn. De linkstructuur biedt grafdoorzoekmogelijkheden aléméte sleutelwoordzoektochten.

Dit is steeds relevanter voor engineers die hun eigen kennisbasis willen queryn met een LLM in plaats van elke keer van vooraf aan te beginnen.

Veelvoorkomende valkuilen

Te breed schrijven

Een notitie die een heel onderwerp behandelt is geen evergreen notitie — het is een conceptartikel. Als je notitie langer is dan een enkel scherm en meer dan één bewering behandelt, breek hem op in kleinere notities en link ze.

Te smal schrijven

Een notitie die te specifiek is voor één context heeft geen herbruikingswaarde. “Fixte de facturatie service cache bug op 2024-03-14” is een logboek, geen evergreen notitie. Verhoog het abstractieniveau tot het idee van toepassing is in minimaal drie verschillende contexten.

“Evergreen” verwarren met “Verandert nooit”

Evergreen betekent niet immuteabel. Het betekent dat de notitie het waard blijft om terug te keren naar. Een notitie over Go generics geschreven in 2022 is nog steeds evergreen als je hem updatet om weer te geven hoe patronen evolueerden in 2024. Een notitie die je nooit aanraakt omdat je gelooft dat hij permanent correct is, is een notitie die uiteindelijk in stilte fout zal worden.

De verwerkingsstap overslaan

De meest voorkomende falen is het behandelen van evergreen notities als een verzameldoel in plaats van een schrijfpraktijk. Je kunt geen verzameling van hoogwaardige atome notities laten groeien door bladwijzers op te slaan. De evergreen notitie is niet het artikel dat je las — het is wat je eruit extracteerde in je eigen woorden.

Tools

Obsidian

Obsidian is het populairste tool voor evergreen notities. Zijn lokale Markdown bestanden, bidirectionele links en grafweergave aligneren goed met de praktijk. Een eenvoudige structuur:

vault/
  fleeting/
    daily/
  literature/
  evergreen/
  maps/       ← index notities voor clusters van evergreen notities

De grafweergave in Obsidian maakt linkclusters zichtbaar — nuttig voor het ontdekken welke concepten natuurlijke groepen vormen die indexnotities of gepubliceerde artikelen kunnen worden.

Plain Markdown met Git

Een Git repository van Markdown bestanden werkt goed en heeft geen afhankelijkheid van enig specifiek tool. Standaard Markdown links verbinden notities. Zoeken wordt afgehandeld door je editor of grep. Versiegeschiedenis komt van Git.

knowledge/
  evergreen/
    caching/
    api-design/
    performance/
  literature/
  fleeting/

De discipline is hetzelfde ongeacht het tool — één idee per notitie, geschreven in je eigen woorden, gelinkt aan gerelateerde notities.

Starten vanaf nul

De meest nuttige manier om te beginnen is niet om je bestaande notities te migreren. Het is om vandaag één evergreen notitie te schrijven.

Neem iets wat je de laatste week hebt geleerd. Schrijf het als een bewering. Verklaar het in je eigen woorden in één alinea. Voeg links toe aan nul of één gerelateerde ideeën.

Dat is een complete evergreen notitie. Herhaal het één keer per week voor zes maanden en je hebt een werkend systeem.

Het composterende effect kost tijd om zichtbaar te worden. Engineers die evergreen notities onderhouden voor een jaar rapporteren vaak dat hun notities vragen beginnen te beantwoorden voordat ze ze afmaken — omdat ze het antwoord al hebben geschreven in een vorige context.

Eindgedachten

De reden waarom evergreen notities werken is niet dat ze beter zijn in opslag. Ze zijn beter in denken. De discipline van het schrijven van één draagbaar idee per notitie, in je eigen woorden, met links naar gerelateerde ideeën, forceert begrip dat passieve verzameling niet doet.

Voor engineers heeft dit praktische consequenties. De notities van een productieincident die je verwerkt naar evergreen formaat zijn nuttiger dan het incidentlogboek. De ontwerpafweging die je distilleert naar een atome notitie is nuttiger dan het architectuurschema. Het debugpatroon dat je generaliseert van een specifieke bug is meer herbruikbaar dan het ticket.

Gebruikt naast de PARA methode voor het organiseren van actief werk, geven evergreen notities je de conceptuele laag die PARA niet biedt — een groeiend netwerk van herbruikbaar begrip dat blijft bestaan across projecten, across rollen, en across jaren.