Description
I've been collaborating with Marc and reflecting on how we might evolve the Dapr documentation to better serve developers—especially those new to the project. Over time, as the project has grown, so has the documentation. While this is a great sign of maturity, it also presents an opportunity: to revisit how the content is structured so that it scales with clarity and consistency.
I’ve spent time thinking through the documentation from the perspective of a developer encountering Dapr for the first time, and how we might guide them more intuitively through the journey of understanding, adopting, and contributing to the project.
I'd like to propose the following layout to reorganize all the documentation across the website in a more consistent and structured manner:
Getting Started
Allow new developers to quickly understand, install and try Dapr
What is Dapr?
High-level overview
Key use cases
Architecture at a glance
Sidecar pattern, building blocks
Quickstart
Install Dapr API
Run your first app
Minimal cURL-based examples using the CLI
Next steps
Choose your language
Explore SDKs
Tutorials/Dapr University
Foundations
Core ideas that underpin how Dapr works, organized by conceptual role
Architectrue
Sidecar pattern
Dapr runtime
Hosting models
Self-hosted, Kubernetes
Deployment models
Sidecar, shared
Communication model
HTTP/gRPC, service discovery
Building Blocks
Service Invocation
State Management
Publish & Subscribe
Input/Output Bindings
Actors
Cryptography
Secrets Management
Configuration
Distributed Lock
Jobs
Workflow
Conversation
Component Model
What is a component?
Component categories
Building blocks vs pluggable components
SDKs
Language-specific guides, tools and tutorials - building out .NET, but the same would apply throughout as applicable/available
.NET
Overview
What this SDK is and what it offers
Supported platforms and environments
Current version and changelog
Release notes
Compatibility with Dapr runtime versions
Installation
Package manage instructions
Nuget, chocolatey, etc.
System requirements
Optional dependencies
e.g. for Actors or Workflows support
Using the SDK
For each building block available use the following consistent structure:
Service Invocation
Overview
- What this block does
- How it maps to the runtime capabilities
- Supported transport (HTTP/gRPC)
Generic SDK usage
- Installation, configuration & registration
- Code examples using the SDK directly
- CLI or raw API comparison (if helpful)
- Error handling & retries
- Troubleshooting tips
Framework-specific usage
- Integration with supported frameworks (e.g. ASP.NET Core)
- Dependency injection
- Middleware/filters
- Framework-specific properties (e.g. attributes)
- Example projects, quickstarts, examples
- Framework-specific troubleshooting
Testing & Mocking
- Unit/integration testing strategies
- Mocking Dapr APIs or SDK clients
- Test containers or local emulators (if available)
Framework-Specific Guidance - for each framework (e.g. ASP.NET Core):
- Setup & integration
- Dependency injection/registration
- Middleware
IDE Integration (for each IDE):
- Project setup
- Debugging Dapr sidecars and apps
- Running and inspecting tests
- Screenshots & walkthroughs
Developer Tooling & Experience
Cross-Cutting Tooling
- Aspire (with orchestration examples & screenshots)
- Dapr Dashboard
- Dev containers, Docker compose, Helm charts
Language-Specific Enhancements
Source Generators
- What they do and why to use them
- How to install/enable/configure them
- Example use cases (e.g. generate actor proxies)
Code Analyzers
- Linting rules
- IDE integration
- Suppression and customization
Scaffolding & Templates
- Project generators/templates
Testing & Debugging Utilities
- Local test harnesses
Troubleshooting
Common errors & resolutions
Logging and diagnostics
SDK-specific error codes (if applicable)
How to report issues
Contribution Guide
Help contributors understand how to work on the SDK itself
- How to clone and build the SDK
- Directory structure and module layout
- Code formatting and style guide
- Testing strategy and how to run integration/unit tests
- How to submit PRs
-- Branching strategy - Maintainer contact, review & triage process
Capability Matrix
- Shared table across all SDKs, but linked to from each SDK page that reflects building block support by SDK - full, partial/in progress, not supported)
- Shows which building blocks and features are supported
- Updated with each SDK release
- Helps set expectations and identify contribution opportunities
Go
Java
JavaScript
PHP
Python
Rust
Advanced Topics
For developers deploying Dapr in production or tuning it
Resiliency (retries, timeouts, circuit breakers)
Security (mTLS, access control, secrets, namespaces)
Multi-tenancy & Isolation
Observability (logs, metrics, tracing)
Error handling (error codes, diagnostics)
Performance & Scalability (sidecar tuning, resource usage, benchmarks)
Production Readiness
Version Migration Preparedness
Custom Components & Extensibility
Reference
Canonical, exhaustive technical details
CLI Reference
HTTP API Reference
gRPC API Reference
Component Specification Reference
Resource Specification Reference
Deployment annotations
Environment variables
Error Codes
Terminology Glossary
Community
How to get involved and stay connected
Contribution guide
Governance
Roadmap
Community Meetings
Announcements
Support Channels
This isn't a small change and I recognize the scope. But I believe this can be the right time to start this conversation - especially as we look ahead to the 1.17 release. A more structured, consistent, and developer-centic documentation experience will not only reduce friction for new users but also empower contributors and maintainers alike.
I'd be happy to support this effort in a significant way and I would welcome feedback from the community on how we can shape this together.
Thank you for your time and consideration!