Restructure Durable Objects docs around Diátaxis framework

[elithrar]

‼️ trying something out and seeing what sticks here. the current navigation and docs structure is complex and has grown organically to a state where it's hard to navigate and find useful content. users are not on a journey. they're in a soup.

Restructure the Durable Objects documentation using the Diátaxis framework to clearly separate tutorials, how-to guides, reference, and explanation.

proposed structure

Pages to create

Page	Type	Source
get-started/your-first-durable-object.mdx	Tutorial	WebSocket examples + new content
concepts/how-durable-objects-work.mdx	Explanation	Merge what-are-durable-objects + lifecycle + reference/in-memory-state
concepts/storage.mdx	Explanation	Extracted from best-practices + API pages
concepts/networking.mdx	Explanation	Extracted from best-practices/websockets + RPC content
concepts/design-patterns.mdx	Explanation	Reworked from rules-of-durable-objects
how-to/index.mdx	Navigation	New section
how-to/access-storage.mdx	How-to	Moved from best-practices/access-durable-objects-storage
how-to/use-websockets.mdx	How-to	Moved from best-practices/websockets
how-to/invoke-methods.mdx	How-to	Moved from best-practices/create-durable-object-stubs-and-send-requests
how-to/use-alarms.mdx	How-to	Merged from api/alarms + examples/alarms-api
how-to/configure-migrations.mdx	How-to	Moved from reference/durable-objects-migrations
how-to/configure-data-location.mdx	How-to	Moved from reference/data-location
how-to/test-durable-objects.mdx	How-to	Moved from examples/testing-with-durable-objects
how-to/handle-errors.mdx	How-to	Moved from best-practices/error-handling
how-to/use-environments.mdx	How-to	Moved from reference/environments
tutorials/build-a-chat-room.mdx	Tutorial	New (from WebSocket examples)
tutorials/build-a-rate-limiter.mdx	Tutorial	New

changes

Page	Disposition
concepts/what-are-durable-objects.mdx	Merged into concepts/how-durable-objects-work.mdx
concepts/durable-object-lifecycle.mdx	Merged into concepts/how-durable-objects-work.mdx
reference/in-memory-state.mdx	Merged into concepts/how-durable-objects-work.mdx
best-practices/* (entire section)	Dissolved — content moves to how-to/ and concepts/
reference/* (entire section)	Dissolved — content moves to how-to/, platform/, concepts/
examples/websocket-server.mdx	Absorbed into tutorials/build-a-chat-room
examples/websocket-hibernation-server.mdx	Absorbed into tutorials/build-a-chat-room
examples/alarms-api.mdx	Absorbed into how-to/use-alarms
examples/testing-with-durable-objects.mdx	Moved to how-to/test-durable-objects

fixes

All api/* pages: change pcx_content_type from concept to reference.

phases

Phase 1 — Create how-to section, fix content types

Move existing pages into how-to/ with minimal rewriting. Fix pcx_content_type on all API reference pages. Add redirects for every moved URL. Dissolve best-practices/ and reference/ sections. This is mostly file moves and frontmatter changes.

Phase 2 — Consolidate concepts

Merge what-are-durable-objects, lifecycle, and in-memory-state into a single how-durable-objects-work.mdx. Create storage.mdx, networking.mdx, and design-patterns.mdx as focused explanation pages. Strip explanation content out of how-to pages and link to these instead.

Phase 3 — Improve tutorials

Rework get-started to follow Diátaxis tutorial principles (visible results at every step, minimal explanation, "we" language). Write the chat room and rate limiter tutorials. Create your-first-durable-object.mdx as an extended tutorial.

Phase 4 — Clean up API reference

Strip how-to content from API pages (link to how-to guides instead). Ensure consistent format across all reference pages: description, methods/properties, parameters, return types, short usage example.

[github-actions]

Hey there, we've marked this pull request as stale because there's no recent activity on it. This label helps us identify long-standing issues in our repo (and not used to auto-close issues).