Auto-Documentation from a Typed System📋

The Thesis📋

To document, you must first type. To type, you must own C# as your DSL. Once typed, documentation becomes a compiler output — not a human activity.

This series introduces the Document DSL — a typed system for generating documentation from other typed systems. Document<Feature<>> generates a traceability matrix. Document<DeploymentOrchestrator<>> generates a deployment runbook. Document<Document<>> generates its own reference docs — the recursive proof that the pattern is self-sustaining.

The infrastructure is C# itself: attributes declare intent, source generators produce artifacts, Roslyn analyzers guard boundaries, projects compose them. Each DSL is a NuGet. Each dotnet build generates documentation. Zero manual authoring. Zero drift.

Table of Contents📋

Part I: The Gotcha — To Document, First You Type📋

You can't auto-generate documentation from nothing. The prerequisite is a typed system. C# is already the infrastructure — attributes, source generators, analyzers. This website proves it: TypeScript types → generated toc.json, meta tags, Mermaid SVGs. The C# version scales it to enterprise.

Part II: The Dev-Side DSLs — What We Already Have📋

The dev DSLs (DDD, Requirements, Testing, API) are the typed foundation. Each follows Attribute + SG + Analyzer + NuGet. They already contain enough metadata for complete documentation — the Document DSL just needs to read them. Plus: the Artifact Graph that finds all consumers automatically.

Part III: The Document DSL — A DSL That Documents DSLs📋

Document<T> is a generic DSL that introspects any other DSL and generates appropriate documentation. Pluggable strategies: Document<Feature<T>> → traceability matrix, Document<AggregateRoot<T>> → architecture diagram. Document<Document<>> documents itself. Onboarding: 1 attribute + 1 <ProjectReference> + dotnet build.

Part IV: The Ops Meta-DSL — An Ecosystem of Sub-DSLs📋

The Ops layer is a composition of 5 independently published sub-DSLs: Deployment, Migration, Observability, Configuration, Resilience. Each a standalone NuGet with its own attributes, source generators, and analyzers. Full attribute definitions with usage examples.

Part V: Composing the Ops DSLs — A Real Deployment📋

One deployment class composes all 5 sub-DSLs. OrderServiceV24Deployment: 3 apps, 2 databases, parallel migrations, canary strategy, 20+ typed attributes. OPS001–OPS012 analyzer diagnostics catch cross-DSL violations at compile time.

Part VI: What Gets Generated — Real Outputs📋

Not just Markdown. Real infrastructure artifacts: Grafana dashboard JSON, Prometheus alert YAML, Kubernetes readiness probes, Helm values. Side-by-side: 45-line stale wiki runbook vs. 120-line always-current generated runbook.

Part VII: Full-Lifecycle Documentation📋

One dotnet build generates documentation spanning Requirement → Feature → Code → Test → Deployment → Monitoring. DocumentSuite<T> ties it all together. Cross-references, release notes, and the pipeline from build to static site.

Part VIII: Complete Example — From Requirement to Dashboard📋

One feature, end-to-end: requirement definition, domain implementation, API, tests, deployment, monitoring. Every generated artifact shown. One feature. 17 generated files. Zero manual documentation.

Part IX: The Meta-Pattern — Documentation as Compiler Output📋

The Grand Unification Table across all blog series: CMF, Contention, Typed Specs, Auto-Doc, Ops. Same meta-pattern, different outputs. Document<Document<>> — the recursive proof. Where this leads: the compiler as technical writer.

How to Read This Series📋

Architects should read Parts I–III + IX for the vision, the Document DSL design, and the meta-pattern synthesis.

Developers should read Parts III–VI for the Document DSL implementation, the Ops sub-DSLs, and the generated outputs.

Ops / SRE engineers should read Parts IV–VIII for the Ops DSL ecosystem, the generated Grafana/Prometheus/K8s artifacts, and the end-to-end walkthrough.

Everyone should read Part VIII — the complete example ties every concept to a single, concrete feature.

Prerequisites📋

• Familiarity with C# attributes and source generators
• Basic understanding of Roslyn analyzers (see Contention over Convention)
• Understanding of DDD concepts (see Building a Content Management Framework)

Related Posts📋

• Contention over Convention over Configuration over Code — the Attribute → SG → Analyzer meta-pattern this series builds upon
• Building a Content Management Framework — the M3/M2/M1 meta-metamodel and the 6 dev-side DSLs
• Onboarding Typed Specifications — the TypeScript proof-of-concept for typed requirements
• Requirements as Code — the C# Requirements DSL that the Document DSL reads