Struggle to Document

I don't remember if I have ever met a developer who genuinely enjoys documentation.

Almost all of us have faced that moment where we open our own code after a few months and suddenly nothing makes sense anymore. Yet somehow, even that experience is not enough to make us document things properly.

The problem is that real documentation is exhausting.

Writing comments beside functions is easy. But documenting the actual architecture of a system why a decision was made, how data flows through services, why one abstraction exists instead of another takes serious mental effort.

Most of the time we skip it because we assume:
“future me will understand this.”

Future me never does.

Over time I realized documentation is less about explaining syntax and more about preserving context. Code usually survives longer than the reasoning behind it.

That is why I started organizing everything inside Obsidian into three separate sections:

• Decisions
  Why something exists. Tradeoffs, rejected approaches, constraints, assumptions.

• Architecture
  High-level flow of the system. How components communicate and how requests move through the system.

• Explanations
  Low-level internals. How a particular mechanism actually works behind the scenes.

For example, while documenting how a Kubernetes Custom Resource is fetched:

The architecture notes may contain:

1. Create Kubernetes client

2. Fetch object

3. Update status

4. Reconcile state

But the explanation section contains the deeper details:

• how client.Get(...) works internally

• serialization/deserialization logic

• informer cache behavior

• reconciliation mechanics

• how controller-runtime abstracts API calls

This separation made documentation far more maintainable for me because the flow and the internals stopped fighting each other.

I still dislike documentation.
But I dislike losing system context even more.
syntax die slowly but context as soon as you switch to new project.