Merge pull request #146 from nikomatsakis/vision-document-pr

add story, some FAQs

Author: nikomatsakis

src/SUMMARY.md

@@ -45,6 +45,7 @@
       - [Grace tries new libraries](./vision/status_quo/grace_tries_new_libraries.md)
       - [Grace waits for gdb next](./vision/status_quo/grace_waits_for_gdb_next.md)
       - [Grace wants to integrate a C-API](./vision/status_quo/grace_wants_to_integrate_c_api.md)
+      - [Niklaus builds a hydrodynamics simulator](./vision/status_quo/niklaus_simulates_hydrodynamics.md)
       - [Niklaus wants to share knowledge](./vision/status_quo/niklaus_wants_to_share_knowledge.md)
    - [✨ Shiny future](./vision/shiny_future.md)
       - [Template](./vision/shiny_future/template.md)

src/vision/how_to_vision/shiny_future.md

@@ -71,30 +71,43 @@ The goal is that, at the end of the review process, the status quo story has a l
 
 ## 🤔 Frequently Asked Questions
 
-### **What is the process to propose a shiny future story?**
+### What is the process to propose a shiny future story?
 * Just open a PR [using this template][template].
 * Do not add your file to [`SUMMARY.md`], that will create conflicts. We'll do it after merging.
 
-### **What character should I use for my shiny future story?**
+### What character should I use for my shiny future story?
 * Usually you would use the same character from the status quo story you are retelling.
 * If for some reason you chose a different character, add a FAQ to explain why.
 
-### **What do I do if there is no status quo story for my shiny future?**
+### What do I do if there is no status quo story for my shiny future?
 [Write the status quo story first!](./status_quo.md)
 
-### **How much detail should I give? How specific should I be?**
+#### What happens when there are multiple "shiny future" stories about the same thing?
+
+During this brainstorming period, we want to focus on getting as many ideas as we can. Having multiple "shiny futures" that address the same problem is a feature, not a bug, as it will let us mix-and-match later to try and find the best overall plan.
+
+### How much detail should I give? How specific should I be?
 * Detailed is generally better, but only if those details are helpful for understanding the morals of your story.
 * Specific is generally better, since an abstract story doesn't feel as real.
 
-### **What do I do when I get to details that I don't know yet?**
+#### What is the "scope" of a shiny future story? Can I tell shiny future stories that involve ecosystem projects?
+
+All the stories in the vision doc are meant to cover the full "end to end" experience of using async Rust. That means that sometimes they will take about things that are really part of projects that are outside of the Rust org. For example, we might write a shiny future that involves how the standard library has published standard traits for core concepts and those concepts have been adopted by libraries throughout the ecosystem. There is a FAQ that asks you to talk about what kinds of coordinate between projects will be required to realize this vision.
+
+### What do I do when I get to details that I don't know yet?
 Take your best guess and add a FAQ explaining which details are still up in the air.
 
-### **What do I do if I don't know that my idea is technically feasible?**
-You don't have to know how your idea will work yet. You can add FAQs to try and clarify what parts you do know and what parts still need to be figured out.
+### Do we have to know exactly how we will achieve the "shiny future"?
 
-### **What do I do if somebody leaves a comment about how my idea will work and I don't know the answer?**
+You don't have to know how your idea will work yet. We will eventually have to figure out the precise designs, but at this point we're more interested in talking about the experience we aim to create. That said, if you do have plans for how to achieve your shiny future, you can also include [design docs] in the PR, or add FAQ that specify what you have in mind (and perhaps what you have to figure out still).
+
+### What do I do if somebody leaves a comment about how my idea will work and I don't know the answer?
 Add it to the FAQ!
 
+### What if we write a "shiny future" story but it turns out to be impossible to implement?
+
+Glad you asked! The vision document is a living document, and we intend to revisit it regularly. This is important because it turns out that predicting the future is hard. We fully expect that some aspects of the "shiny future" stories we write are going to be wrong, sometimes very wrong. We will be regularly returning to the vision document to check how things are going and adjust our trajectory appropriately.
+
 [template]: https://github.com/rust-lang/wg-async-foundations/tree/master/src/vision/shiny_future/template.md
 [sfd]: https://github.com/rust-lang/wg-async-foundations/tree/master/src/vision/shiny_future
 [`SUMMARY.md`]: https://github.com/rust-lang/wg-async-foundations/blob/master/src/SUMMARY.md