Define a better docs IA for AppHost/AppModel, integrations, and runtimes

[davidfowl]

Summary

Aspire needs a clearer docs Information Architecture (IA) now that it supports:

• JavaScript and Python apps (13.0)
• TypeScript AppHost (13.2)

Today the docs still often read as if Aspire is fundamentally a C# AppHost product with everything else layered on later.

Problem

The docs currently mix several different axes:

• AppHost / AppModel features
• Core integrations (Aspire.Hosting)
• Technology-specific integrations
• Architecture / mental model
• Templates / tooling
• AppHost authoring language (C#, TypeScript)
• Application runtime (.NET, JavaScript, Python, etc.)
• Deployment target

Because these are mixed together, the docs drift toward a C#-first mental model even when the feature is AppHost-wide or language-neutral.

The core taxonomy

The docs should start from these primary content domains:

1. AppHost / AppModel features

   • core AppModel concepts
   • endpoints
   • networking
   • DCP
   • orchestration behavior

2. Core integrations

   • built-in Aspire.Hosting resource types and hosting capabilities

3. Integrations

   • technology-specific integrations that extend the app model

4. Architecture

   • conceptual and system-design docs

5. Templates / tooling

   • project creation and scaffolding

These should be kept distinct from the cross-cutting dimensions:

• AppHost authoring language
• application runtime
• deployment target

IA options

Option 1: Domain-first IA

Primary structure:

• Get started
• AppHost / AppModel
• Core integrations
• Integrations
• Architecture
• Deployment
• Reference

Language/runtime stay secondary.

Inspiration: Pulumi

Option 2: Concepts + explicit language/runtime areas

Primary structure:

• Get started
• AppHost / AppModel
• Core integrations
• Integrations
• Architecture
• Languages / runtimes
• Deployment
• Reference

Shared concepts stay language-neutral. Language/runtime-specific guidance gets its own area.

Inspiration: OpenTelemetry

Option 3: Workflow-first core docs

Primary structure:

• Get started
• Build your AppHost
• Add apps and resources
• Connect integrations
• Deploy and operate
• Architecture / advanced topics
• Reference

Language-specific guidance is handled through parallel entry points or docsets.

Inspiration: Playwright

Recommendation

The likely best direction is a Pulumi + OpenTelemetry hybrid:

• keep the primary IA domain-first
• make language/runtime support explicit
• keep shared AppHost/AppModel docs language-neutral
• use language-specific areas only for authoring/runtime-specific behavior and gaps

That makes Option 1 the easiest incremental path and Option 2 the strongest long-term model.

Documentation rules

• Use C# / TypeScript tabs when the feature is the same and only the authoring syntax differs.
• Use separate pages when the content is really about an authoring model, runtime, or materially different workflow.
• Avoid treating C# as the default mental model on generic pages.

Open questions

• Where should templates live?
• Should core Aspire.Hosting docs be their own IA bucket?
• Should authoring languages and application runtimes live in one shared area or separate areas?
• Should runtime docs stay under Integrations or move out into their own area?

Goal

Choose the IA direction first, then use that decision to drive follow-up restructuring work.