Why these docs exist

Birdor documentation exists for a very specific reason:

Most developer documentation optimizes for getting started fast.
Birdor documentation optimizes for staying understandable long after you started.

In real projects, the hardest problems rarely appear on day one.
They appear months later—when code has grown, contributors have changed, and decisions made early begin to matter.

Birdor docs are written to support that phase.

They are not:

• Marketing pages
• API reference dumps
• Copy-paste tutorials detached from real systems

They are:

• Decision records
• Engineering constraints explained in plain language
• Examples that reflect real maintenance costs
• Guidance for thinking, not just typing

The Birdor documentation philosophy

1. Explicit over clever

Birdor documentation assumes that:

• Hidden behavior creates long-term cost
• Magic reduces debuggability
• Implicit conventions decay faster than explicit structure

As a result, the docs intentionally:

• Explain why something is designed a certain way
• Show wiring and composition explicitly
• Avoid “just trust the framework” guidance

2. Architecture before features

Many docs are organized by features:

routing, middleware, auth, database, cache…

Birdor docs are organized by architecture and responsibility:

• boundaries
• lifecycles
• ownership
• failure modes
• evolution paths

Features are discussed within those contexts, not in isolation.

3. Long-term readability is a first-class goal

A Birdor document should still make sense:

• after six months
• after a team handover
• after partial rewrites
• after production incidents

That means:

• minimal jargon without explanation
• stable terminology
• no dependency on “current trends”
• fewer assumptions about tooling

What these docs cover today

Core topics

The documentation currently focuses on:

• Plumego

  • Philosophy and scope
  • When to use it — and when not to
  • Architectural best practices
  • Real, complete examples (User / Auth / Project)
  • Roadmap and design constraints

• Engineering decisions

  • Why explicit wiring is preferred
  • Why dependency injection is optional
  • Why standard library alignment matters
  • Why some features are intentionally not included

• Operational thinking

  • Error modeling
  • Request lifecycles
  • Debuggability
  • Observability as a design concern, not an add-on

These docs are intentionally opinionated—but always explain the tradeoffs.

What these docs are not

To avoid confusion, it is important to be explicit about what you will not find here.

Birdor docs are not:

• A replacement for Go’s official documentation
• A generic web-framework tutorial
• A “one-size-fits-all” guide
• A shortcut to avoid learning fundamentals

They assume:

• You are willing to think about structure
• You care about maintenance, not just delivery
• You value clarity over cleverness

How the documentation is structured

At a high level, the docs are organized into:

• Getting Started

  • Orientation and mental models
  • Minimal runnable examples

• Best Practices

  • Layering and boundaries
  • Error handling
  • Context usage
  • Module composition

• FAQ

  • Why Plumego exists
  • Why not Framework X
  • When Plumego is a bad fit
  • Common mistakes and misconceptions

• Roadmap

  • Current state
  • Planned evolution
  • Explicit non-goals
  • Stability guarantees

Each section is designed to stand on its own, while still fitting into a coherent whole.

The current state of the docs

Today, Birdor documentation is:

• Actively evolving
• Written alongside real code and real projects
• Refined through usage, not speculation

This means:

• Some sections will grow over time
• Some guidance may be sharpened as patterns prove themselves
• Changes will prioritize clarity and backward understanding

Stability is preferred—but correctness comes first.

Where the documentation is going

The long-term plan for Birdor docs includes:

1. Deeper real-world examples

• Larger, multi-module services
• Multi-tenant patterns
• Background jobs and async flows
• Realtime and event-driven architectures

2. Decision-focused documents

• “Why this exists”
• “Why this is intentionally missing”
• “What breaks if you change this”

3. Operational maturity

• Production checklists
• Failure case walkthroughs
• Migration and refactoring strategies
• Debugging narratives based on real incidents

4. A stable knowledge base

The goal is not to grow endlessly.

The goal is to reach a point where:

Most future questions can be answered by linking to an existing document.

How to read these docs

If you are new:

1. Start with the introduction pages
2. Read at least one complete example
3. Skim the FAQ, especially the “why not” sections

If you are evaluating Plumego:

• Focus on tradeoffs, not features
• Pay attention to what is explicitly excluded
• Compare mental models, not syntax

If you are maintaining a system:

• Treat these docs as reference material
• Use them to validate or challenge existing decisions
• Adapt patterns, do not blindly copy them

A final note

Birdor documentation is written with a simple assumption:

Good systems are built by people who understand why things exist—not just how to use them.

If these docs help you:

• slow down in the right places
• make fewer irreversible decisions
• keep your system understandable over time

then they are doing their job.

Welcome to the Birdor documentation.