Evergreen Notes: Write Notes That Compound Over Time

Most engineering notes are written once and forgotten. You capture something during a debugging session, paste it into a doc, and rediscover it two years later with no context for why it mattered.

The problem is not effort. Engineers write constantly — code comments, Slack messages, Confluence pages, Jira descriptions, pull request explanations, architecture diagrams. The problem is that most of those notes are written for a specific moment and age poorly. They do not compound. They accumulate.

Evergreen notes are the alternative. The idea is simple: write each note so that it stays useful indefinitely, improves when you revisit it, and connects to other notes in a way that makes the whole system more valuable over time.

The term was popularized by researcher Andy Matuschak, whose own public notes demonstrate the idea at scale. For engineers, the principle has direct applications in technical writing, documentation, architecture decisions, and the long-term capture of hard-won lessons.

What Makes a Note Evergreen

Atomic

An evergreen note contains one idea. Not one topic — one idea.

A note called "PostgreSQL" is not evergreen. It is a container waiting to be filled. A note called "Partial indexes reduce write overhead when queries target a small subset" is evergreen. It states a specific, portable claim.

The atomic constraint is important because it controls reuse. A container note can only be linked as a vague topic. An atomic note can be linked wherever that specific idea applies — in a discussion of query optimization, in a comparison of indexing strategies, in a project note about a specific performance problem.

Standalone

An evergreen note should be understandable without its original source.

That means writing in your own words. A note that says "See the linked article — good stuff on caching" is not evergreen. A note that says "Write-through caching updates the cache synchronously with the database on every write, improving read consistency at the cost of higher write latency" is evergreen. You can read it a year later without chasing the original source.

This is harder than it sounds. Writing a standalone note requires actually understanding what you read, not just tagging it. That processing step is where most of the learning happens.

Evolving

Evergreen notes improve over time rather than going stale.

A fleeting note has a lifecycle: you write it, it serves a moment, it becomes irrelevant. An evergreen note should be worth revisiting and refining six months or two years later. You might add a counterexample, update it with a production experience, link it to a new pattern, or simply rewrite it more precisely.

The word "evergreen" is intentional: these notes do not die after harvest. They persist and improve.

Linked

Evergreen notes connect to other notes rather than sitting in isolation.

A standalone note about write-through caching connects naturally to notes about read-heavy workloads, cache invalidation, eventual consistency, and database write performance. Each link makes both notes more useful — the connection surfaces context that neither note contains alone.

The linking habit is what turns a collection of individual insights into a network of connected understanding.

Note Types and When to Use Each

Understanding evergreen notes requires understanding what they are not.

Fleeting notes are temporary captures. A line scribbled during a debugging session, a bookmark to revisit, a question to follow up on. Fleeting notes serve a moment. They should be processed quickly and either discarded or promoted into something more durable. Most fleeting notes never become evergreen notes, and that is fine.

Literature notes are summaries of external sources — a documentation page, a postmortem, a book chapter, a conference talk. Literature notes preserve what a source said. They are a step toward understanding, not understanding itself. A literature note says "this source claims X." An evergreen note says "I believe X for these reasons."

Evergreen notes synthesize what you have come to understand. They live at the output of the learning process, not the input.

Writing Evergreen Technical Notes

The structure of a good evergreen technical note follows a simple logic: claim, evidence, implication.

# Write-through caching improves read consistency at the cost of write latency

Write-through caching updates the cache at the same time as the underlying store
on every write. Every read hits fresh data because the write path ensures
consistency before the write is acknowledged.

The tradeoff is write latency — every write now requires two operations (store
and cache) to complete before the caller receives a confirmation.

This pattern suits read-heavy workloads where cache staleness has real
business impact, such as product inventory counts or user settings.

Links:
- [[Read-through caching shifts cache population to read time]]
- [[Cache invalidation is a coordination problem]]
- [[Write-behind caching trades consistency for write throughput]]

That note is useful without the source. It states the claim, explains the tradeoff, gives a context where it applies, and links to related ideas.

What to Avoid

Time-sensitive references age badly. "As of Postgres 14, this behavior works this way" is a literature note, not an evergreen note. Write the principle instead: "The planner skips index scans when estimated row count exceeds a threshold relative to table size." That claim survives version changes even if the threshold changes.

Tool-specific commands without context are snippets, not notes. A note that is just a kubectl command copied from a StackOverflow answer is not evergreen. A note about why that command works — what Kubernetes resource it affects and what problem it solves — has a chance.

Assumptions about reader knowledge degrade fast. Write as if explaining to a competent colleague who is not inside your current context.

Good Candidates for Evergreen Notes in Engineering

Almost any hard-won lesson with broad applicability is a good candidate:

• Architecture tradeoffs and the reasoning behind decisions
• Debugging patterns that apply across systems
• API design rules and their edge cases
• Performance characteristics with real-world numbers attached
• Security assumptions that turned out to be wrong
• Test strategy lessons from projects where the approach failed
• Deployment constraints that changed how the team worked

The common thread: specific enough to be actionable, general enough to apply more than once.

The Evergreen Workflow

Step 1: Capture Fleeting Notes

Capture quickly without overthinking. The goal is not to produce an evergreen note in the moment — it is to preserve the raw material for one.

During a debugging session:

Found that the cache was returning stale user permissions after role changes.
The TTL was 5 minutes but the role update was immediate.
Need to think through how to handle this — invalidation on write?
Or shorter TTL? Or event-driven update?

That is a fleeting note. It is not an evergreen note, but it contains the seeds of several.

Step 2: Process Into Evergreen Notes Within 48 Hours

Processing is where the value appears. Take the raw capture and extract the ideas that are worth preserving.

From that debugging note, you might write:

# Role-based cache entries require invalidation on write, not just TTL expiry

When cached data encodes permissions or roles, TTL-based expiry is not safe.
A user whose role is downgraded keeps elevated permissions until the TTL expires.
Write-time invalidation — or event-driven cache updates on role change — is required
for correctness in permission-sensitive caches.

Links:
- [[Cache invalidation is a coordination problem]]
- [[Authorization decisions should not be cached at rest without validation]]

The debugging context is gone. The portable idea remains.

Step 3: Connect to Existing Notes

After writing the note, spend two minutes asking:

• What existing note does this relate to?
• What concept does this depend on?
• What does this extend or contradict?

Add links in both directions. The new note links to existing notes. Existing notes that are now richer for the connection link back.

Step 4: Revisit and Improve

Evergreen notes do not have a single correct state. Every time you encounter the idea again — in a production incident, a design review, a code review comment — consider returning to the note and making it better.

You might:

• Add a more concrete example
• Update the claim based on new evidence
• Remove a caveat that turned out not to matter
• Add a link to a new related note
• Rewrite the opening sentence for clarity

That cycle of refinement is what makes notes compound rather than decay.

Evergreen Notes and Documentation

There is a useful distinction between personal evergreen notes and team documentation.

Personal evergreen notes are your understanding, written for future you. They can be rough, opinionated, and incomplete. Their value is in being reusable for your thinking.

Team documentation is for shared understanding. It needs accuracy, accessibility, and maintenance ownership.

The two layers complement each other. Your evergreen notes about why a system was designed a certain way can become the raw material for the architecture decision record. Your debugging notes can feed the runbook. Your API design notes can inform the style guide.

The direction of flow is usually: evergreen notes → polished documentation, not the reverse.

Evergreen Notes and RAG Systems

As AI-augmented knowledge tools become more practical, well-written evergreen notes become increasingly valuable as retrieval source material. The retrieval versus representation problem in knowledge management is essentially about quality of source material — and evergreen notes, being atomic, standalone, and written for comprehension, chunk well for vector search.

A Zettelkasten of atomic evergreen notes is a natural foundation for a personal RAG system. The atomic structure aligns with retrieval chunk size. The standalone property means retrieved notes need no additional context to be useful. The linking structure provides graph traversal opportunities beyond keyword search.

This is increasingly relevant for engineers who want to query their own knowledge base with an LLM rather than starting from scratch each time.

Common Pitfalls

Writing Too Broadly

A note that covers an entire topic is not an evergreen note — it is a draft article. If your note is longer than a single screen and covers more than one claim, break it into smaller notes and link them.

Writing Too Narrowly

A note that is too specific to one context has no reuse value. "Fixed the billing service cache bug on 2024-03-14" is a log entry, not an evergreen note. Raise the abstraction level until the idea applies in at least three different contexts.

Confusing "Evergreen" With "Never Changes"

Evergreen does not mean immutable. It means the note remains worth returning to. A note about Go generics written in 2022 is still evergreen if you update it to reflect how patterns evolved in 2024. A note that you never touch because you believe it is permanently correct is a note that will eventually become wrong in silence.

Skipping the Processing Step

The most common failure is treating evergreen notes as a collection target rather than a writing practice. You cannot grow a collection of high-quality atomic notes by saving bookmarks. The evergreen note is not the article you read — it is what you extracted from it in your own words.

Tools

Obsidian

Obsidian is the most popular tool for evergreen notes. Its local Markdown files, bidirectional links, and graph view align well with the practice. A simple structure:

vault/
  fleeting/
    daily/
  literature/
  evergreen/
  maps/       ← index notes for clusters of evergreen notes

The graph view in Obsidian makes link clusters visible — useful for discovering which concepts form natural groups that might become index notes or published articles.

Plain Markdown With Git

A Git repository of Markdown files works well and has no dependency on any specific tool. Standard Markdown links connect notes. Search is handled by your editor or grep. Version history comes from Git.

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

The discipline is the same regardless of tool — one idea per note, written in your own words, linked to related notes.

Starting From Zero

The most useful way to start is not to migrate your existing notes. It is to write one evergreen note today.

Take something you learned in the last week. Write it as a claim. Explain it in your own words in one paragraph. Add links to zero or one related ideas.

That is a complete evergreen note. Repeat once per week for six months and you have a working system.

The compounding effect takes time to become visible. Engineers who maintain evergreen notes for a year often report that their notes start answering questions before they finish asking them — because they have already written the answer in a previous context.

Final Thoughts

The reason evergreen notes work is not that they are better at storage. They are better at thinking. The discipline of writing one portable idea per note, in your own words, with links to related ideas, forces understanding that passive collection does not.

For engineers, this has practical consequences. The notes from a production incident that you process into evergreen format are more useful than the incident log. The design tradeoff you distill into an atomic note is more useful than the architecture diagram. The debugging pattern you generalize from a specific bug is more reusable than the ticket.

Used alongside the PARA method for organizing active work, evergreen notes give you the conceptual layer that PARA does not provide — a growing network of reusable understanding that persists across projects, across roles, and across years.