Skip to content

ADR 0014: Elevate Site from Documentation Collection to Cohesive Systems Doctrine

  • Status: Accepted
  • Date: 2026-02-26
  • Deciders: Joshua Grant
  • Technical Story: Transition the site from a growing collection of tutorials and analytical essays into a coherent, navigable systems-level doctrine.

Context

The site has evolved beyond tutorials and best practices into a substantial body of analytical deep dives covering:

  • Distributed systems
  • Storage theory
  • Observability
  • Data architecture
  • Embedded systems
  • Infrastructure economics
  • Geospatial systems

While the intellectual depth has increased, structural cohesion has not kept pace.

The risks are:

  • Content silos
  • Cognitive overload for new readers
  • Redundant arguments across deep dives
  • Lack of narrative entry points
  • Weak conceptual mapping between sections

The site is at an inflection point: It can either become a loosely connected archive, or a structured intellectual framework.

Decision

We will introduce structural layers that transform the site into a cohesive systems doctrine:

  1. Architectural Entry Points
  2. A “Start Here” decision tree page

  3. Curated Reading Tracks

  4. Thematic Cohesion

  5. Cross-cutting theme declarations
  6. A Decision Framework Index

  7. An Anti-Patterns Index

  8. Intellectual Framing

  9. A “Philosophy of the Site” page
  10. A Systems Thinking Glossary

  11. A Canon / Recommended Reading order

  12. Cross-Section Synthesis

  13. Meta-essays connecting deep dives

  14. Explicit cross-links between related doctrines

  15. Intentional Structure

  16. Minimal redundancy
  17. Clear semantic relationships
  18. Designed, not accumulated navigation

Alternatives Considered

1. Continue Adding Content Without Structural Reform

Rejected. This risks fragmentation and reader fatigue.

2. Create an External Blog for Philosophy

Rejected. The philosophy is intrinsic to the technical content and should remain integrated.

3. Major Structural Rewrite

Rejected. We prefer incremental, compositional refinement.

Consequences

Positive

  • Increased intellectual cohesion
  • Clear onboarding path for new readers
  • Stronger narrative continuity
  • Reduced conceptual redundancy
  • Elevated authority and intentionality

Negative

  • Additional structural overhead
  • Increased editorial discipline required
  • Slightly more complex navigation

Follow-ups

  • Implement "Start Here" decision tree
  • Add Reading Tracks page
  • Add Decision Framework Index
  • Add Anti-Patterns index
  • Add Philosophy page
  • Add Systems Glossary
  • Introduce light thematic labeling

Governance

Future deep dives must:

  • Declare themes
  • Cross-link to at least two existing essays
  • Avoid duplication of core arguments
  • End with a structured decision framework