Vision²
aka, so you want to visioneer
(nikomatsakis, tmandry)
Sound familiar?
You see a big opportunity: a change that could have big impact.
But there are a lot of details to work out.
And a lot of stakeholders, each arguing for something different.
You might need a vision doc.

Vision docs…
- …can help us scale up open source design.
- …can help us stay focused on our goals.
- …can help us find alignment.
- …are hard to do.
- That's where this presentation comes in!
Let's go back to January…

Shane: "Let's talk about what Rust should be like in a few years!"
Me, at the time:

Me, a few days later:

Why was it hard?
- What are the most imp't problems?
- Complex space, too much for one person
- Little consensus, distinct subcommunities
Idea: Let's build it together
What are the most imp't problems?
- Status quo narratives help you understand
Complex, too much for one person
- Survey and assemble the bigger picture
- Engage stakeholders directly
- let them tell us what's important
Little consensus
- Lift the focus from the details to the impact
Shiny future I see

Active projects of a certain scope develop a vision doc
- Async
- Const generics and const evaluation
- Embedded?
- Error handling?
- FFI and interop?
People can use vision docs to see where Rust is going
"Ah, I can't wait for that version of Rust."
Team members can use vision docs to place an RFC in context
"OK, I see what we're trying to do and how this gets us there."
Parts of a vision doc
- Characters and projects
- Status quo
- Shiny future
Status quo stories
From Alan needs async in traits:
Alan is working on a project with Barbara. He is working on abstracting away the HTTP implementation the library uses.
Alan tries to create the async trait:
trait HttpClient {
async fn perform(request: Request) -> Response;
}
When he tries to compile this, he gets the error:
--> src/lib.rs:2:5
|
2 | async fn perform(request: Request) -> Response;
| -----^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
| |
| `async` because of this
|
= note: `async` trait functions are not currently supported
= note: consider using the `async-trait` crate: https:
Story goes on to tell:
- How he tries the async-trait crate
- Learns how it works
- Tries to support a
#[no_std]
environment
Key points about status quo
- Describe current experience in narrative form
- Include specific details – stay true to life!
- If covering controversial things, stick to the facts, describe what character experiences
- Can involve multiple characters
Don't skip the status quo

Status quo writing sessions
Organizing group writing sessions can be really fun:
- One person driving, shared hackmd
- Other people sharing their experiences
- Start with rough overview with major points
- Try to knit them together into a story
- If you get stuck, ask someone:
Missing step: organizing status quo stories
- Group things into the biggest problems
- Brainstorm the possible solutions to those problems
- without diving into too many details
Explore the space
- Not sure how something should be?
- Write it out multiple ways!
- Writing a story is a fast way to explore the future
Don't get too hung up in the how
- Focus on the user experience
- We can figure out how to do it
- or something that feels similar
Expect to get it wrong

Revisit the shiny future as we make progress and learn new things
Some questions to chew on
- Might your project benefit from a vision doc?
- Would the characters work for you?
- When is the right time to try a vision doc?
- How can we "scale down" the vision doc?
Vision² aka, so you want to visioneer (nikomatsakis, tmandry)
{"metaMigratedAt":"2023-06-16T00:18:51.735Z","metaMigratedFrom":"YAML","title":"3: Vision²","breaks":true,"contributors":"[{\"id\":\"27d8f2ac-a5dc-4ebe-8c31-cc45bcd8447e\",\"add\":14459,\"del\":8135}]"}