Improve Durable Objects intro by saying what it does. #19298
Conversation
kentonv
requested review from
elithrar,
vy-ton,
joshthoward,
Oxyjun and
a team
as code owners
github-actions
bot
added
the
product:durable-objects
Deploying cloudflare-docs with
|
| Latest commit: |
0e86518
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://28b1937b.cloudflare-docs-7ou.pages.dev |
| Branch Preview URL: | https://kenton-improve-do-intro.cloudflare-docs-7ou.pages.dev |
|
Files with changes (up to 15)
|
kentonv
changed the title
There is a lot of debate about how best to present DOs so that people "get it". Engineers (like me) usually want to know what a product *does*. This is contrary to the common wisdom that product pages should say what problems a product *solves*. Figuring out how to use a tool to solve a problem is an engineer's job, so as long as they know what it does, they can figure out what it solves. Conversely, if you only tell them what it solves, they then cannot visualize *how* it solves the problem, which is their job, so they get frustrated. To that end, we should very briefly explain what a Durable Object *does* right on the landing page.
kentonv
force-pushed
the
kenton/improve-do-intro
branch
from
8460593 to
442f6d0
Compare
Parts of this felt redundant with the newly-added section below. Also, I wanted to work in a mention of deeper distributed systems. Durable Objects are not just about collaborative apps.
|
We really need a broader overview too, before "Get started". The "get started" page launches right into steps to sign up and create my first DO class but a lot of people will want to understand more about the product before they're ready to do that. How can we fit that in? I see the "overview" followed by "get started button" followed by "features" section is a standard layout across many products, but I feel like it's a poor fit here. Can I add a whole bunch more text to this landing page? Or should we create a separate "extended overview" page and link to it? How can we make that link prominent? |
My preference would be a new page (or two). But, one page talking about what DO is, what it offers, how to think about it, benefits, things developers don't need to think about, and a few use-cases as examples. Page titles: Learn Durable Objects, Introduction to Durable Objects, Understanding Durable Objects, What are Durable Objects |
The extended overview/concepts page should be separate from this DO product landing page. @Oxyjun can help identify the right location and cross links. |
There is a lot of debate about how best to present DOs so that people "get it".
Engineers (like me) usually want to know what a product does. This is contrary to the common wisdom that product pages should say what problems a product solves. Figuring out how to use a tool to solve a problem is an engineer's job, so as long as they know what it does, they can figure out what it solves. Conversely, if you only tell them what it solves, they then cannot visualize how it solves the problem, which is their job, so they get frustrated.
To that end, we should very briefly explain what a Durable Object does right on the landing page.