change

src/FAQ.md

@@ -0,0 +1 @@
+# ❓ FAQ

src/SUMMARY.md

@@ -5,9 +5,9 @@
     - [⚙️ Reliable](./how_rust_feels/reliable.md)
     - [🐎 Performant](./how_rust_feels/performant.md)
     - [💪🏽 Empowering](./how_rust_feels/empowering.md)
+    - [🔧 Transparent and tunable](./how_rust_feels/transparent.md)
     - [💎 Polished](./how_rust_feels/polished.md)
     - [🤸 Versatile](./how_rust_feels/versatile.md)
-    - [📜 Case studies](./how_rust_feels/case_study.md)
 - [How to Rustacean](./how_to_rustacean.md)
     - [💖 Be kind and considerate](./how_to_rustacean/be_kind.md)
     - [✨ Bring joy to the user](./how_to_rustacean/bring_joy.md)
@@ -17,3 +17,5 @@
     - [✅ Follow through](./how_to_rustacean/follow_through.md)
     - [🤝 Pay it forward](./how_to_rustacean/pay_it_forward.md)
     - [🎁 Trust and delegate](./how_to_rustacean/trust_and_delegate.md)
+- [📜 Case studies](./case_studies.md)
+- [❓ FAQ](./FAQ.md)

src/how_rust_feels.md

@@ -14,10 +14,14 @@ This section identifies the way that Rust ought to feel, when everything is goin
 
 > Rust offers a wide selection of libraries and abstractions that can be quickly combined to create complex applications. 
 
+## [🔧 Transparent and tunable](./how_rust_feels/transparent.md): "able to predict low-level details and control them"
+
+> The translation from Rust to underlying machine code is predictable. If needed, you have options to control the low-level details of how your application works.
+
 ## [💎 Polished](./how_rust_feels/polished.md): "Rust gets the big *and* the small things right"
 
 > Rust is built with an attention to detail. Whether it's the error messages, the tooling, or the details of the type system or APIs, we try to anticipate and meet our users' needs, along with things they didn't know they wanted.
 
 ## [🤸 Versatile](./how_rust_feels/versatile.md): "whatever it is I want to do, I can use Rust to do it"
 
-> Rust can be used to build everything from simple scripts to web servers to WebAssembly programs to kernel extensions and embedded systems. Rust gives you the ability to control low-level details and exposes the capabilities of the underlying system.
+> Rust scales well both up and down: it is well-suited to building everything from simple scripts to web servers to WebAssembly programs to kernel extensions and embedded systems. 

src/how_rust_feels/transparent.md

@@ -0,0 +1 @@
+# 🔧 Transparent and tunable

src/what_is_this.md

@@ -1 +1,25 @@
-# What is this?
+# Rustacean Principles
+
+Rust is...
+
+* a language empowering everyone to build reliable and efficient software that is meant to last;
+* an open-source community focused on creating, designing, and maintaining that language and its ecosystem.
+
+The **Rustacean principles** are a set of principles which guide us in achieving those goals.
+
+* The first section, [How Rust ought to feel](./how_rust_feels.md), covers the underlying design principles of Rust.
+* The second section, [How to Rustacean](./how_to_rustacean.md), describes the way that Rust team members are expected to act. You can think of it like a companion to the [Code of Conduct][CoC]: whereas the [CoC] describes the bare minimum expected of any Rust participant, the [How to Rustacean] section describes what is takes to become a member of a Rust team.
+* The third section, [Case studies](./case_studies.md), walks through various examples of things in Rust and shows how they reflect a balance amongst the design principles.
+
+## 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