The Meta-Pattern — Documentation as Compiler Output📋

"Declare intent with a type. Let the compiler produce the artifact. The only variable is what gets generated — code, enforcement, or documentation."

The Grand Unification Table📋

Four blog series. One pattern. Five steps. Different outputs.

The pattern is always:

Attribute (declare intent)
    → Source Generator (read intent, produce artifact)
        → Analyzer (guard boundaries, report violations)
            → Output (code, docs, infra — depends on the SG)

The only thing that changes across series is what the SG emits. The infrastructure is the same. The developer experience is the same. The compiler does the work.

One Attribute, Many Outputs📋

A single [AggregateRoot] attribute on Order now drives outputs from five different series:

[AggregateRoot(BoundedContext = "Ordering")]
[ForRequirement(typeof(OrderPaymentFeature))]
[Injectable(Lifetime.Scoped)]
public partial class Order
{
    [EntityId] public partial OrderId Id { get; }
    [Composition] public partial IReadOnlyList<OrderLine> Lines { get; }
    [Composition] public partial PaymentInfo Payment { get; }

    [DomainEvent(typeof(OrderPaidEvent))]
    public Result MarkAsPaid(PaymentReference ref, PaymentMethod method) { ... }
}

One class. Three attributes. Seven generators. Twenty files. Zero manual documentation.

The Gotcha Revisited📋

Part I stated the gotcha: to document, first you type.

Now we see the full picture:

The Investment📋

Typing is the investment. Adding [AggregateRoot], [ForRequirement], [DeploymentOrchestrator], [HealthCheck] to your code takes time. Each attribute is a declaration of intent that costs a few seconds to write.

The Payoff📋

Everything else is free:

• Architecture diagrams → generated
• Traceability matrices → generated
• API documentation → generated
• Deployment runbooks → generated
• Grafana dashboards → generated
• Prometheus alerts → generated
• Kubernetes probes → generated
• Helm values → generated
• Release notes → generated
• Cross-references → generated

The investment is one-time per concept. The payoff compounds with every build.

This Website Proved It📋

This site started with TypeScript interfaces (TocItem, Heading, TocSection) and a build pipeline (build-static.ts). The investment was typing the content metadata. The payoff was auto-generated toc.json, meta tags, JSON-LD, Mermaid SVGs, and a fully navigable SPA.

The C# version scales the same principle to enterprise: DDD aggregates, requirements, API contracts, deployments, observability — all typed, all auto-documented.

Document<Document<>> — The Recursive Proof📋

The Document DSL documents itself. Document<Document<>> generates the Document DSL's own reference documentation:

• List of all registered strategies and their output formats
• All active Document<> declarations in the solution
• All DOC001–DOC005 analyzer diagnostics with descriptions
• Coverage: which DSLs have documentation strategies, which don't

If you can document the documenter, the pattern is self-sustaining. No external tool needed. No separate documentation system. The typed system documents itself, including the system that does the documenting.

This is not a gimmick — it has practical value:

• New team members see exactly which documentation strategies exist
• The reference updates automatically when a new strategy is registered
• Missing strategies are visible (e.g., "Ops.Configuration has attributes but no DocumentStrategy")

When Auto-Doc Goes Too Far📋

Honest limitations:

What Auto-Doc Cannot Generate📋

• Narrative context — "Why did we choose this payment provider?" has no attribute
• Decision records — architectural decisions are human reasoning, not typed metadata
• Tutorial content — step-by-step guides require a narrative voice
• User-facing documentation — end-user docs need empathy and tone, not traceability

The Human Role Shifts📋

Auto-documentation doesn't eliminate the human. It shifts the role from author to editor:

The human writes the "why." The compiler writes the "what."

The Decision Matrix📋

DX Recap — The Three-Line Promise📋

For any team using typed DSLs:

<!-- Line 1: Add the Document DSL -->
<ProjectReference Include="Cmf.Document.Lib" />

// Line 2: Declare what to document
[assembly: DocumentSuite<Order>(CrossReference = true)]

# Line 3: Build
dotnet build
# → 15+ documentation files generated
# → Grafana dashboard ready to import
# → Prometheus alerts ready to deploy
# → Kubernetes probes ready to apply

No configuration files. No template systems. No documentation plugins. The types you already wrote ARE the documentation source. The Source Generator you already use IS the documentation engine.

Where This Leads📋

The Compiler as Technical Writer📋

Documentation is no longer a human activity separate from development. It is a compiler output — as automatic as IL generation, as reliable as type checking, as up-to-date as the code itself.

The Build as Documentation Pipeline📋

dotnet build doesn't just compile your application. It generates your documentation, your infrastructure artifacts, your compliance reports, and your release notes. One command. One source of truth.

The PR as Changelog📋

When a developer adds a [Feature] or modifies an [AggregateRoot], the Document DSL regenerates the affected docs. The PR diff shows both the code change and the documentation change. The reviewer sees the impact on both code and docs in one place.

The Release as Runbook📋

When a new [DeploymentOrchestrator] is tagged for release, the generated runbook IS the release procedure. The generated Helm values ARE the deployment configuration. The generated Prometheus alerts ARE the monitoring setup. Nothing else to write.

Series Summary📋

The investment is typing. The payoff is everything else.