wip

src/SUMMARY.md

@@ -7,12 +7,12 @@
         - [Consider all cases](./how_rust_empowers/reliable/consider_all_cases.md)
     - [🐎 Performant](./how_rust_empowers/performant.md)
         - [Zero-cost abstractions](./how_rust_empowers/performant/zca.md)
-        - [Specify only what's necessary](./how_rust_empowers/performant/zca.md)
+        - [Specify only what's necessary](./how_rust_empowers/performant/specify_what_is_necessary.md)
     - [🥰 Supportive](./how_rust_empowers/supportive.md)
         - [Polished developer experience](./how_rust_empowers/supportive/polished.md)
     - [🧩 Productive](./how_rust_empowers/productive.md)
         - [Ecosystem](./how_rust_empowers/productive/ecosystem.md)
-        - [Upgrades are easy and painless](./how_rust_empowers/productive/ecosystem.md)
+        - [Stability](./how_rust_empowers/productive/stability.md)
     - [🔧 Transparent](./how_rust_empowers/transparent.md)
         - [No global costs](./how_rust_empowers/transparent/no_global_costs.md)
     - [🤸 Versatile](./how_rust_empowers/versatile.md)

src/how_rust_empowers/performant/specify_what_is_necessary.md

@@ -0,0 +1 @@
+# Specify only what's necessary

src/how_rust_empowers/performant/zca.md

@@ -1 +1,5 @@
 # Specify only what's necessary
+
+Rust borrowed the idea of zero-cost abstractions from the C++ community. Bjarne Stroustroup defined zero-cost abstractions as, "What you don't use, you don't pay for. And further: What you do use, you couldn't hand code any better." We design our abstractions with these goals in mind as well.
+
+TODO elaborate

src/how_rust_empowers/productive/stability.md

@@ -0,0 +1 @@
+# Stability

src/how_rust_empowers/reliable.md

@@ -17,9 +17,14 @@ Reliability can also be at odds with [versatility]. Our ability to make somethin
 
 What are some of the ways that we make Rust feel **reliable**?
 
-* [Type safety](./reliable/type_safety.md): Safe Rust code is guaranteed to avoid undefined behavior.
-    * *Why it makes Rust code feel reliable:* Segfaults and data races are the hardest kind of bug to diagnose and fix.
-    * *Trades off:* Type safety makes the system more complex, which works against being [supportive]; it also requires the entire system to be brought into a consistent state, which can work against [productivity].
-* [Consider all cases](./reliable/consider_all_cases.md): Rust doesn't hide error conditions and encourages listing all possibilities explicitly (or acknowledging that something is elided).
-    * *Why it makes Rust code feel reliable:* Listing all cases often highlights things that the programmer has forgotten about.
-    * *Trades off:* As with type safety, considering all cases means that the system must be brought into a consistent state, which can work against [productivity].
+### [Type safety](./reliable/type_safety.md)
+
+> Safe Rust code is guaranteed to avoid undefined behavior.
+
+Rust programmers never have to worry about notorious, hard-to-diagnose, harder-to-fix bugs like segfaults and data races. Rust's exposure to security vulnerabilities is much reduced as a result. However, static safety comes at the cost of increased overall complex (works against [supportive]). Figuring out the correct type annotations and other details can be difficult, working against [productivity].
+
+### [Consider all cases](./reliable/consider_all_cases.md)
+
+> Rust doesn't hide error conditions and encourages listing all possibilities explicitly (or acknowledging that something is elided).
+
+Rust uses a number of mechanisms to encourage code authors to list all possibilities. This thoroughness frequently helps identify bugs because it ca highlight things that the programmer has forgotten about. However, it comes at a price in [productivity], since it can force the programmer to deal with details that they haven't figure out yet.

src/how_rust_empowers/reliable/consider_all_cases.md

@@ -1,5 +1,7 @@
 # Consider all cases
 
+> Rust doesn't hide error conditions and encourages listing all possibilities explicitly (or acknowledging that something is elided).
+
 Rust generally aims to make sure that you 'acknowledge' or consider all cases. You can see this in `match` statements, which require exhaustive matching (many other languages permit you to leave off match arms that you believe cannot occur); when matching, we also require that users list all fields in a struct, or acknowledge (with `..`) that they have not done so. Forcing users to consider all cases helps make Rust feel reliable, but it can come at the cost of feeling [productive]. This is why we frequently pay careful attention to the details of 
 
 A good case study for the tradeoffs involved is error handling. The traditional approach to error handling for a long time was exceptions. Exceptions are great for feeling [productive], as they allow errors to quietly pass through any amount of code. However, the result is a proliferation of hidden control-flow paths that are very hard to reason about. In practice, recovering from exceptions is fraught with error, and hence they work against the feeling of reliability. The problem is that typical mechanisms such as returning an error code are also not reliable; it's too easy to forget to check for an error.

src/how_rust_empowers/reliable/type_safety.md

@@ -1,5 +1,7 @@
 # Type safety (but with an unsafe escape hatch)
 
+> Safe Rust code is guaranteed to avoid undefined behavior.
+
 Type safety is a key element to reliability. We ensure that safe Rust code is free of "undefined behavior", which is the term that compiler authors use to refer to things like segfaults, data races, and out-of-bounds memory accesses.
 
 Type safety is not a suggestion: we don't accept **almost safe** APIs, which are safe so long as you don't do "unreasonable" things. For example, we would not accept a safe API that avoids undefined behavior so long as no cycles exist between ref-counted objects. Reasonable people do "unreasonable" things in code all the time, either because they don't yet know what is reasonable or not, or because the complexity of the system gets away from them. The role of the compiler is to manage that for you.