more

src/FAQ.md

@@ -1 +1,10 @@
 # ❓ FAQ
+
+## Who developed these principles? Are they "official"?
+
+No -- right now, this is a work-in-progress being developed by nikomatsakis in collaboration with lots of people within the Rust community. When it takes settled shape, it may indeed move to the Rust org as something more official.
+
+## Why develop these principles?
+
+The goal of these principles is to help us to be more precise as we go about our work in the Rust org. The [Rust empowers by being...](./how_rust_empowers.md) section is primarily intended to help guide discussions about the effects of features on our users. The [How to Rustacean](./how_to_rustacean.md) section is meant to help us in describing the kinds of behaviors that we are looking for when we select Rust team members. This makes it hard for people to know what they ought to do, but it also makes it very hard for us to communicate where improvement is needed.
+

src/case_studies.md

@@ -0,0 +1,36 @@
+# Case studies
+
+What follows are a list of short examples of elements of Rust's design. For each one, we elaborate on some of the 
+
+Key:
+
+* 💚 -- strong improvement
+* 🟡 -- mildly better or mildly worse
+* ❌
+
+## Type safety, unsafe code, and verification: a delicate balance
+
+| Feature     | Reliable | Performant | Productive | Supportive | Transparent | Versatile |
+| ----------- | -------- | ---------- | ---------- | ---------- | ----------- | --------- |
+| Type safety | 😎      |            | 😎        |            | 😓         | 😓       |
+
+## The `?` operator: a delicate balance
+
+| Feature          | Reliable | Performant | Productive | Supportive | Transparent | Versatile |
+| ---------------- | -------- | ---------- | ---------- | ---------- | ----------- | --------- |
+| The `?` operator | 💚      | 🟡        | 🟡        | 🟡        | 💚         | 💚       |
+
+## Coherence: a key feature, but one perhaps ready to be revisited
+
+| Feature   | Reliable | Performant | Productive | Supportive | Transparent | Versatile |
+| --------- | -------- | ---------- | ---------- | ---------- | ----------- | --------- |
+| Coherence | 💚      |            | 💚        |            | ❌         | ❌       |
+
+Rust's ["coherence rules"](https://doc.rust-lang.org/reference/items/implementations.html?highlight=coherence#trait-implementation-coherence) are limits on the sets of impls that people are allowed to write in their crates. The goal is to ensure that, no matter what crates you grab from crates.io and add to your dependency list, there is also a consistent (one might say "coherent") set of impls -- and we never have the problem where there are two different `Hash` impls defined for a given type (for example). Those kinds of situations can lead to subtle bugs or other errors.
+
+These rules serve an essential function, but they can also be severely limiting and a source of frustration. They are probably a good example of a language feature that ought to be adjusted, because of their severe impact on versatility and transparency (but which cannot be removed entirely, because they are needed for reliability and productivity).
+
+**😎 Productive:** It may surprise you to hear coherence described as a win for producitivity, given that it *prevents* you from writing impls you might have otherwise liked to write (and indeed this is reflected in its impact on versatility). The reason that coherence helps productivity is because the rules are setup to ensure that any two crates on crates.io can be combined without linker errors or surprising behavior. 
+
+**😎 Reliabie:** Coherence 
+

src/how_rust_empowers/productive.md

@@ -4,6 +4,15 @@
 
 ## Examples
 
+### Cargo and crates.io
+
+
+
+
 ### Stability without stagnation and editions
 
-One of Rust's [core deliverables](https://blog.rust-lang.org/2014/10/30/Stability.html) 
+One of Rust's [core deliverables](https://blog.rust-lang.org/2014/10/30/Stability.html) 
+
+### Portability
+
+Rust code aims to be portable across all mainstream architectures by default.

src/what_is_rust.md

@@ -1,5 +1,7 @@
 # Rustacean Principles
 
+<img src="/image/dancing-ferris.gif" alt="Dancing Ferris" width="300"></img>
+
 ## What is Rust?
 
 * A language **empowering everyone to build reliable and efficient software**.
@@ -13,15 +15,5 @@ Rust is developed and maintained by the members of its [various teams](https://w
 
 Finally, the [case studies](./case_studies.md) section applies both the previous sections to various examples from Rust's history, and shows how the principles can help guide us.
 
-## Why develop these principles?
-
-The goal of these principles is to help us to be more precise as we go about our work in the Rust org. The [How Rust ought to feel](./how_rust_feels.md) section enumerates the kinds of considerations we should consider, and can help us to think more carefully about designs. For example, when we are considering a change, we can talk about whether it works against "it compiles it works" in favor of "empowering", and look for previous case studies that made similar tradeoffs.
-
-The [How to Rustacean](./how_to_rustacean.md) is similar. We've often had a hard time elaborating on the kinds of behaviors that we are looking for when we select Rust team members. This makes it hard for people to know what they ought to do, but it also makes it very hard for us to communicate where improvement is needed.
-
-## Is this "official"?
-
-No -- right now, this is a work-in-progress being developed by nikomatsakis in collaboration with lots of people within the Rust community. When it takes settled shape, it may indeed move to the Rust org as something more official.
-
 [CoC]: https://www.rust-lang.org/policies/code-of-conduct
 [How to Rustacean]: ./how_to_rustacean.md