cloudflare / cloudflare/cloudflare-docs

Restructure Durable Objects docs around Diátaxis framework

Open
#28,344 1 comment 0 reactions 1 assignee Claimed by @elithrar View on GitHub
product:durable-objects stale
Dominant language
MDX
Stars
5.2k
Forks
16.7k
Avg merge
2d 6h
Merged PRs (30d)
337

Description

> ‼️ 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](https://diataxis.fr/) 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.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.