Merge pull request #119 from Stupremee/use-headings-for-faqs

Rework all FAQ Sections to use Headings instead of bullet lists

Author: nikomatsakis

src/design_docs/async_fn_in_traits.md

@@ -84,5 +84,5 @@ trait MyMethod {
 
 ## 🤔 Frequently Asked Questions
 
-* **What do people say about this to their friends on twitter?**
-    * (Explain your key points here)
+### **What do people say about this to their friends on twitter?**
+* (Explain your key points here)

src/vision/characters.md

@@ -28,14 +28,16 @@ We've created four characters that we use to guide our thinking. These character
 
 ## 🤔 Frequently Asked Questions
 
-* Where do the names come from?
-    * Famous programming language designers and theorists. [Alan Turing], [Grace Hopper], [Niklaus Wirth], and [Barbara Liskov].
-* I don't see myself in these characters. What should I do?
-    * Come to Zulip and talk to us about it! Maybe they need to be adjusted!
-* I see myself in more than one of these characters!
-    * Yeah, me too.
+### Where do the names come from?
+Famous programming language designers and theorists. [Alan Turing], [Grace Hopper], [Niklaus Wirth], and [Barbara Liskov].
+
+### I don't see myself in these characters. What should I do?
+Come to Zulip and talk to us about it! Maybe they need to be adjusted!
+
+### I see myself in more than one of these characters!
+Yeah, me too.
 
 [Alan Turing]: https://en.wikipedia.org/wiki/Alan_Turing
 [Grace Hopper]: https://en.wikipedia.org/wiki/Grace_Hopper
 [Niklaus Wirth]: https://en.wikipedia.org/wiki/Niklaus_Wirth
-[Barbara Liskov]: https://en.wikipedia.org/wiki/Barbara_Liskov
+[Barbara Liskov]: https://en.wikipedia.org/wiki/Barbara_Liskov

src/vision/characters/alan.md

@@ -16,7 +16,8 @@ Alan is developing networking programs in Kotlin. He loves Kotlin for its expres
 
 ## 🤔 Frequently Asked Questions
 
-* What does Alan want most from Async Rust?
-    * The promise of better performance and memory usage than the languages he's been using. Rust's safety guarantees are important too; he's considered using C++ in the past but always judged the maintenance burden would be too high.
-* What expectations does Alan bring from his current environment?
-    * A focus on ease of use, a strong ecosystem, and great tooling.
+### What does Alan want most from Async Rust?
+* The promise of better performance and memory usage than the languages he's been using. Rust's safety guarantees are important too; he's considered using C++ in the past but always judged the maintenance burden would be too high.
+
+### What expectations does Alan bring from his current environment?
+* A focus on ease of use, a strong ecosystem, and great tooling.

src/vision/characters/barbara.md

@@ -8,9 +8,10 @@ Barbara has been using Rust since the 0.1 release. She remembers some of the cra
 
 ## 🤔 Frequently Asked Questions
 
-* What does Barbara want most from Async Rust?
-    * She is using Rust for its feeling of productivity, and she expects Async Rust to continue in that tradition.
-    * She maintains several existing projects, so stability is important to her.
-* What expectations does Barbara bring from her current environment?
-    * She wants a design that feels like the rest of Rust.
-    * She loves Rust and she expects Async Rust to share its overall values.
+### What does Barbara want most from Async Rust?
+* She is using Rust for its feeling of productivity, and she expects Async Rust to continue in that tradition.
+* She maintains several existing projects, so stability is important to her.
+
+### What expectations does Barbara bring from her current environment?
+* She wants a design that feels like the rest of Rust.
+* She loves Rust and she expects Async Rust to share its overall values.

src/vision/characters/grace.md

@@ -8,8 +8,9 @@ Grace has been writing C and C++ for a number of years. She's accustomed to hack
 
 ## 🤔 Frequently Asked Questions
 
-* What does Grace want most from Async Rust?
-    * Grace is most interested in memory safety. She is comfortable with C and C++ but she's also aware of the maintenance burden that arises from the lack of memory safety.
-* What expectations does Grace bring from her current environment?
-    * Grace expects to be able to get the same performance she used to get from C or C++.
-    * Grace is accustomed to various bits of low-level tooling, such as gdb or perf. It's nice if Rust works reasonably well with those tools, but she'd be happy to have access to better alternatives if they were available. She's happy using `cargo` instead of `make`, for example.
+### What does Grace want most from Async Rust?
+Grace is most interested in memory safety. She is comfortable with C and C++ but she's also aware of the maintenance burden that arises from the lack of memory safety.
+
+### What expectations does Grace bring from her current environment?
+* Grace expects to be able to get the same performance she used to get from C or C++.
+* Grace is accustomed to various bits of low-level tooling, such as gdb or perf. It's nice if Rust works reasonably well with those tools, but she'd be happy to have access to better alternatives if they were available. She's happy using `cargo` instead of `make`, for example.

src/vision/characters/niklaus.md

@@ -8,7 +8,8 @@ He's always been interested in programming but doesn't have experience with it.
 
 ## 🤔 Frequently Asked Questions
 
-* What does Niklaus want most from Async Rust?
-    * Niklaus values accessibility. He's learning a lot of new things at once and it can be overwhelming.
-* What expectations does Niklaus bring from his current environment?
-    * Niklaus expects a strong and supportive community. The Rust community enabled him to have early success, and he is excited to have it support him and for it to help him grow more.
+### What does Niklaus want most from Async Rust?
+* Niklaus values accessibility. He's learning a lot of new things at once and it can be overwhelming.
+
+### What expectations does Niklaus bring from his current environment?
+* Niklaus expects a strong and supportive community. The Rust community enabled him to have early success, and he is excited to have it support him and for it to help him grow more.

src/vision/grace_waits_for_gdb_next.md

@@ -77,15 +77,18 @@ Grace is now able to use `next` to walk through the main function. She does noti
 
 *Here are some standard FAQ to get you started. Feel free to add more!*
 
-* **What are the morals of the story?**
-    * A common usage pattern: hitting `next` to go to what seems like the next statement, breaks down due to implementation details of `#[tokio::main]` and `async fn`.
-    * This is one example of where `next` breaks, in terms of what a user is likely to *want*. The other common scenario where the behavior of `next` is non-ideal is higher-order functions, like `option.and_then(|t| { ... }`, where someone stepping through the code probably *wants* `next` to set
-a temporary breakpoint in the `...` of the closure.
-* **What are the sources for this story?**
-    * Personal experience. I haven't acquired the muscle memory to stop using `next`, even though it breaks down in such cases.
-* **Why did you choose Grace to tell this story?**
-    * I needed someone who, like me, would actually be tempted to use `gdb` even when println debugging is so popular.
-* **How would this story have played out differently for the other characters?**
+### **What are the morals of the story?**
+* A common usage pattern: hitting `next` to go to what seems like the next statement, breaks down due to implementation details of `#[tokio::main]` and `async fn`.
+* This is one example of where `next` breaks, in terms of what a user is likely to *want*. The other common scenario where the behavior of `next` is non-ideal is higher-order functions, like `option.and_then(|t| { ... }`, where someone stepping through the code probably *wants* `next` to set
+  a temporary breakpoint in the `...` of the closure.
+
+### **What are the sources for this story?**
+Personal experience. I haven't acquired the muscle memory to stop using `next`, even though it breaks down in such cases.
+
+### **Why did you choose Grace to tell this story?**
+I needed someone who, like me, would actually be tempted to use `gdb` even when println debugging is so popular.
+
+### **How would this story have played out differently for the other characters?**
     * Alan might have used whatever debugger is offered by his IDE, which might have the same problem (via a toolbar button that has the same semantics as `next`); but many people using IDE's to debugger just naturally set breakpoints by hand on the lines in their IDE editor, and thus will not run into this.
     * Most characters would probably have abandoned using gdb much sooner. E.g. Grace may have started out by adding `println` or `tracing` instrumention to the code, rather than trying to open it up in a debugger.
 

src/vision/how_to_vision/shiny_future.md

@@ -73,24 +73,30 @@ 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?**
-    * 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?**
-    * 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?**
-    * [Write the status quo story first!](./status_quo.md)
-* **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?**
-    * 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.
-* **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 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?**
+* 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?**
+[Write the status quo story first!](./status_quo.md)
+
+### **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?**
+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.
+
+### **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!
 
 [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
+[`SUMMARY.md`]: https://github.com/rust-lang/wg-async-foundations/blob/master/src/SUMMARY.md

src/vision/how_to_vision/status_quo.md

@@ -66,22 +66,27 @@ 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 status quo 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 if my story applies to multiple characters?**
-    * Look at the "morals" of your story and decide which character will let you get those across the best.
-    * Use the FAQ to talk about how other characters might have been impacted.
-    * If the story would play out really differently for other characters, maybe write it more than once!
-* **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 should I do when I'm trying to be specific but I have to make an arbitrary choice?**
-    * Add a FAQ with some of the other alterantives, or just acknowledging that you made an arbitrary choice there.
-* **None of the characters are a fit for my story.**
-    * It doesn't have to be perfect. Pick the one that seems like the closest fit. If you really feel stuck, though, come talk to us on [Zulip] about it!
-* **How should I describe the "evidence" for my status quo story?**
-    * The more specific you can get, the better. If you can link to tweets or blog posts, that's ideal. You can also add notes into the [conversations] folder and link to those. Of course, you should be sure people are ok with that.
+### **What is the process to propose a status quo 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 if my story applies to multiple characters?**
+* Look at the "morals" of your story and decide which character will let you get those across the best.
+* Use the FAQ to talk about how other characters might have been impacted.
+* If the story would play out really differently for other characters, maybe write it more than once!
+
+### **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 should I do when I'm trying to be specific but I have to make an arbitrary choice?**
+Add a FAQ with some of the other alterantives, or just acknowledging that you made an arbitrary choice there.
+
+### **None of the characters are a fit for my story.**
+It doesn't have to be perfect. Pick the one that seems like the closest fit. If you really feel stuck, though, come talk to us on [Zulip] about it!
+
+### **How should I describe the "evidence" for my status quo story?**
+The more specific you can get, the better. If you can link to tweets or blog posts, that's ideal. You can also add notes into the [conversations] folder and link to those. Of course, you should be sure people are ok with that.
 
 [conversations]: ../../conversations.md
 [template]: https://github.com/rust-lang/wg-async-foundations/tree/master/src/vision/status_quo/template.md

src/vision/projects/DistriData.md

@@ -13,14 +13,18 @@ DistriData is the latest in containerized, micro-service distributed database te
 
 ## 🤔 Frequently Asked Questions
 
-* **What makes DistriData different from others?**
-    * This project is meant to be used in many different ways in many different projects, and is not unique to any one application.
-    * Many of those using this project will not even need or want to know that it's written in Rust.
-* **Does DistriData require a custom tailored runtime?**
-    * DistriData's concerns are at a higher level than the runtime. A fast, reliable, and resource conscious general purpose runtime will serve DistriData's needs.
-* **How much of this project is likely to be built with open source components from crates.io?**
-    * Yes, while DistriData receives many contributions, it's important to the team that when possible they utilize existing technologies that developers are already familiar with to ensure that contributing to the project is easy.
-* **What is of most concern to this project?**
-    * It needs to be resource conscious, fast, reliable, but above all else it needs to be easy to run, monitor, and maintain.
-* **What is of least concern to this project?**
-    * While DistriData is resource conscious, it's not resource *starved*. There's no need to make life difficult to save on a memory allocation here or there.
+### **What makes DistriData different from others?**
+* This project is meant to be used in many different ways in many different projects, and is not unique to any one application.
+* Many of those using this project will not even need or want to know that it's written in Rust.
+
+### **Does DistriData require a custom tailored runtime?**
+DistriData's concerns are at a higher level than the runtime. A fast, reliable, and resource conscious general purpose runtime will serve DistriData's needs.
+
+### **How much of this project is likely to be built with open source components from crates.io?**
+Yes, while DistriData receives many contributions, it's important to the team that when possible they utilize existing technologies that developers are already familiar with to ensure that contributing to the project is easy.
+
+### **What is of most concern to this project?**
+It needs to be resource conscious, fast, reliable, but above all else it needs to be easy to run, monitor, and maintain.
+
+### **What is of least concern to this project?**
+While DistriData is resource conscious, it's not resource *starved*. There's no need to make life difficult to save on a memory allocation here or there.