pull out the examples into their own pages

src/SUMMARY.md

@@ -20,11 +20,15 @@
 - [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)
+        - [Improving Rust's compiler messages](./how_to_rustacean/bring_joy/improving_compiler_error.md)
+        - [Responding on an issue](./how_to_rustacean/bring_joy/responding.md)
     - [👋 Show up](./how_to_rustacean/show_up.md)
+        - [Raising an objection about a design](./how_to_rustacean/show_up/raising_an_objection.md)
     - [🔭 Recognize others' knowledge](./how_to_rustacean/recognize_others.md)
     - [🔁 Start somewhere](./how_to_rustacean/start_somewhere.md)
     - [✅ Follow through](./how_to_rustacean/follow_through.md)
     - [🤝 Pay it forward](./how_to_rustacean/pay_it_forward.md)
+        - [Spreading knowledge](./how_to_rustacean/pay_it_forward/spreading_knowledge.md)
     - [🎁 Trust and delegate](./how_to_rustacean/trust_and_delegate.md)
 - [📜 Case studies](./case_studies.md)
 - [❓ FAQ](./FAQ.md)

src/how_to_rustacean/bring_joy.md

@@ -13,27 +13,16 @@ At the same time:
 
 ## Examples
 
-### Designing a tool
+### [Improving Rust's compiler messages](./bring_joy/improving_compiler_error.md)
 
-
-### Improving Rust's compiler messages
-
-Somebody tweets about a terrible error message. It has a type that is 16K long and is completely opaque. "What a stupid language", they say.
+> Somebody tweets about a terrible error message. It has a type that is 16K long and is completely opaque. "What a stupid language", they say.
 
 **Just right:** You reply, "Oh, yeah, that message is terrible. Is the code that caused it something I can see?" You can tell they're frustrated, and that's why they're saying how stupid Rust is. Looking at the code, you realize both (a) how to fix their problem and (b) that a quick patch to the compiler would fix it. You do both. They're happy.
 
-**Too much:** As above, but you put aside the work you've been doing and embark on a refactoring odyssey that slows down compilation time by 22% but also does improve this particular error message.
-
-**Too little:** You reply, telling them that they just don't appreciate what Rust is doing for them.
-
-*Note:* I suppose the right response really depends on what you're focused on! In truth, there's no harm in shrugging and moving on here, or just helping them to fix their code, if fixing error messages is not your thing. There's also no harm in doing a lot of work to address this error, if it's a common case and it's your thing. Slowing down the compiler by 22%, though, that's probably not so great (it will not bring joy to users). But no matter what you do, there's no sense in getting angry at them because they think Rust is stupid. The compiler *is* pretty stupid a lot of the time (like every computer program...).
-
-### Responding on an issue
-
-Someone opens an issue claiming a bug in Rust. In fact, the problem is that their code was relying on an implementation detail of a method in the standard library -- this is despite the fact that the documentation for the function clearly states that this detail may change.
+[What do you do?](./bring_joy/improving_compiler_error.md)
 
-**Just right:** You thank them for higlighting this change, and point out that the problem is actually not a bug in Rust, but rather a change that is within the documentation. If appropriate, you might express sympathy for the impact of this change on them, and you consider if there *may* be a way to better advertise or guard against such impact in the future, but you close the current issue.
+### [Responding on an issue](./bring_joy/responding.md)
 
-**Too much:** You apologize profusely and revert the PR that made the change. You wind up in a long conversation with the 
+> Someone opens an issue claiming a bug in Rust. In fact, the problem is that their code was relying on an implementation detail of a method in the standard library -- this is despite the fact that the documentation for the function clearly states that this detail may change.
 
-**Too little:** You reply curtly, "Not a bug, RTFM", and close the issue.
+[What do you do?](./bring_joy/responding.md)

src/how_to_rustacean/bring_joy/improving_compiler_error.md

@@ -0,0 +1,11 @@
+# Improving Rust's compiler messages
+
+> Somebody tweets about a terrible error message. It has a type that is 16K long and is completely opaque. "What a stupid language", they say.
+
+**Just right:** You reply, "Oh, yeah, that message is terrible. Is the code that caused it something I can see?" You can tell they're frustrated, and that's why they're saying how stupid Rust is. Looking at the code, you realize both (a) how to fix their problem and (b) that a quick patch to the compiler would fix it. You do both. They're happy.
+
+**Too much:** As above, but you put aside the work you've been doing and embark on a refactoring odyssey that slows down compilation time by 22% but also does improve this particular error message.
+
+**Too little:** You reply, telling them that they just don't appreciate what Rust is doing for them.
+
+*Note:* I suppose the right response really depends on what you're focused on! In truth, there's no harm in shrugging and moving on here, or just helping them to fix their code, if fixing error messages is not your thing. There's also no harm in doing a lot of work to address this error, if it's a common case and it's your thing. Slowing down the compiler by 22%, though, that's probably not so great (it will not bring joy to users). But no matter what you do, there's no sense in getting angry at them because they think Rust is stupid. The compiler *is* pretty stupid a lot of the time (like every computer program...).

src/how_to_rustacean/bring_joy/responding.md

@@ -0,0 +1,10 @@
+# Responding on an issue
+
+
+> Someone opens an issue claiming a bug in Rust. In fact, the problem is that their code was relying on an implementation detail of a method in the standard library -- this is despite the fact that the documentation for the function clearly states that this detail may change.
+
+**Just right:** You thank them for higlighting this change, and point out that the problem is actually not a bug in Rust, but rather a change that is within the documentation. If appropriate, you might express sympathy for the impact of this change on them, and you consider if there *may* be a way to better advertise or guard against such impact in the future, but you close the current issue.
+
+**Too much:** You apologize profusely and revert the PR that made the change. You wind up in a long conversation with the 
+
+**Too little:** You reply curtly, "Not a bug, RTFM", and close the issue.

src/how_to_rustacean/pay_it_forward.md

@@ -4,10 +4,8 @@
 
 ## Examples
 
-There's an area of Rust that you may be the only expert on, or one of only a few experts on. You're spending much of your time dealing with issues in that area.
+### [Spreading knowledge](./pay_it_forward/spreading_knowledge.md)
 
-* **Just right**: You give feedback to colleagues, fellow team members, and potentially the broader community, that Rust needs more experts in this area. You prioritize work that allows new or intermediate users to ramp up into your area of expertise. You spend time mentoring others, producing documentation, and similar, sometimes (not always) at the expense of doing the work yourself. You sometimes turn down action items that only you could do, and instead discuss what would need to happen so that that action item doesn't need to get done as urgently.
+> There's an area of Rust that you may be the only expert on, or one of only a few experts on. You're spending much of your time dealing with issues in that area.
 
-* **Too much**: You push back on other changes and obstruct other work on Rust. You try to suggest that further work in a *broader* area shouldn't happen because you're too overloaded. You propose to give up on the whole area because you don't have time for it. You consider the merits of taking up alpaca farming instead of teaching sand to think.
-
-* **Too little**: You lean into your position as the sole expert in the area. You start to brush off new users, other interesting projects, or other aspects of the community, because you don't have the time or bandwidth. You have less fun working on Rust than you used to.
+[What do you do?](./pay_it_forward/spreading_knowledge.md)

src/how_to_rustacean/pay_it_forward/spreading_knowledge.md

@@ -0,0 +1,9 @@
+# Spreading knowledge
+
+> There's an area of Rust that you may be the only expert on, or one of only a few experts on. You're spending much of your time dealing with issues in that area.
+
+* **Just right**: You give feedback to colleagues, fellow team members, and potentially the broader community, that Rust needs more experts in this area. You prioritize work that allows new or intermediate users to ramp up into your area of expertise. You spend time mentoring others, producing documentation, and similar, sometimes (not always) at the expense of doing the work yourself. You sometimes turn down action items that only you could do, and instead discuss what would need to happen so that that action item doesn't need to get done as urgently.
+
+* **Too much**: You push back on other changes and obstruct other work on Rust. You try to suggest that further work in a *broader* area shouldn't happen because you're too overloaded. You propose to give up on the whole area because you don't have time for it. You consider the merits of taking up alpaca farming instead of teaching sand to think.
+
+* **Too little**: You lean into your position as the sole expert in the area. You start to brush off new users, other interesting projects, or other aspects of the community, because you don't have the time or bandwidth. You have less fun working on Rust than you used to.

src/how_to_rustacean/show_up.md

@@ -18,18 +18,8 @@ At the same time:
 
 ## Examples
 
-### Raising an objection about a design
+### [Raising an objection about a design](./show_up/raising_an_objection.md)
 
-You are a member of the Rust lang team and you are concerned about the proposed syntax for a design.
+> You are a member of the Rust lang team and you are concerned about the proposed syntax for a design.
 
-**Just right (and you convince the others):** You raise the objection and make your case for why the syntax is wrong. At first, nobody seems to understand the point you are making, but they extend some trust that you may have a valid point. You try again, this time explaining it from a different angle, and trying to understand and bridge the gap to other people's perspectives and values. This time, it works, and a few members of the team see what you're getting at. After a few more days of discussion, the consensus has shifted, possibly to your proposal or possibly to a new solution that satisfies everyone.
-
-**Just right (and you don't):** You raise the objection and make your case for why the syntax is wrong. At first, nobody seems to understand the point you are making, so you try again, this time explaining it from a different angle. Still, the other members of the team don't agree. They are able to repeat back what you said, including the values you hold that it relates to, and they seem to understand it. but they just don't feel the problem will be as serious as you do, or they feel it's outweighed by other concerns of comparable value and there isn't a solution that satisfies everything. (We should hesitate to select "satisficing" solutions, but sometimes they may be necessary.) At that point, you release your objection. You record a "dissenting opinion", and that opinion is reflected in the "unresolved questions" of subsequent tracking issues, for later re-evaluation before stabilization.
-
-**Too much (blocking progress):** You raise your objection but the rest of the team doesn't seem to agree. You insist that they are wrong and block progress. The team doesn't understand your position and values, and/or you don't understand theirs, so people talk past each other or don't talk at all. Eventually, the whole feature is dropped out of frustration.
-
-**Not enough (giving up too easily):** You raise the objection and make your case for why the syntax is wrong. There is some pushback, and you feel pressure or discomfort maintaining your objection, so you give up and withdraw your concern. Sure enough, though, when the feature is released, the syntax proves to be a major obstacle. You wish you had made your case a bit more forcefully. The overall process would benefit from "forceful" not being a required property of a well-reasoned objection, and would benefit from recording the objection for further examination later in the process.
-
-**Not enough ([cookie licking]):** You leave a comment on the issue stating that you have concerns, but you refuse to engage and discuss them in detail. "I object to this course of action, but I don't have time to get into it right now, and I don't when I will." This does not mean you're wrong for not having the time or energy to get into it, but rather that the process of making a blocking objection requires someone to take the time and energy to explain, discuss it with other members of the team, and convince others; that's part of the expectations from a team member.
-
-[cookie licking]: https://devblogs.microsoft.com/oldnewthing/20091201-00/?p=15843
+[What do you do?](./show_up/raising_an_objection.md)

src/how_to_rustacean/show_up/raising_an_objection.md

@@ -0,0 +1,15 @@
+# Raising an objection about a design
+
+> You are a member of the Rust lang team and you are concerned about the proposed syntax for a design.
+
+**Just right (and you convince the others):** You raise the objection and make your case for why the syntax is wrong. At first, nobody seems to understand the point you are making, but they extend some trust that you may have a valid point. You try again, this time explaining it from a different angle, and trying to understand and bridge the gap to other people's perspectives and values. This time, it works, and a few members of the team see what you're getting at. After a few more days of discussion, the consensus has shifted, possibly to your proposal or possibly to a new solution that satisfies everyone.
+
+**Just right (and you don't):** You raise the objection and make your case for why the syntax is wrong. At first, nobody seems to understand the point you are making, so you try again, this time explaining it from a different angle. Still, the other members of the team don't agree. They are able to repeat back what you said, including the values you hold that it relates to, and they seem to understand it. but they just don't feel the problem will be as serious as you do, or they feel it's outweighed by other concerns of comparable value and there isn't a solution that satisfies everything. (We should hesitate to select "satisficing" solutions, but sometimes they may be necessary.) At that point, you release your objection. You record a "dissenting opinion", and that opinion is reflected in the "unresolved questions" of subsequent tracking issues, for later re-evaluation before stabilization.
+
+**Too much (blocking progress):** You raise your objection but the rest of the team doesn't seem to agree. You insist that they are wrong and block progress. The team doesn't understand your position and values, and/or you don't understand theirs, so people talk past each other or don't talk at all. Eventually, the whole feature is dropped out of frustration.
+
+**Not enough (giving up too easily):** You raise the objection and make your case for why the syntax is wrong. There is some pushback, and you feel pressure or discomfort maintaining your objection, so you give up and withdraw your concern. Sure enough, though, when the feature is released, the syntax proves to be a major obstacle. You wish you had made your case a bit more forcefully. The overall process would benefit from "forceful" not being a required property of a well-reasoned objection, and would benefit from recording the objection for further examination later in the process.
+
+**Not enough ([cookie licking]):** You leave a comment on the issue stating that you have concerns, but you refuse to engage and discuss them in detail. "I object to this course of action, but I don't have time to get into it right now, and I don't when I will." This does not mean you're wrong for not having the time or energy to get into it, but rather that the process of making a blocking objection requires someone to take the time and energy to explain, discuss it with other members of the team, and convince others; that's part of the expectations from a team member.
+
+[cookie licking]: https://devblogs.microsoft.com/oldnewthing/20091201-00/?p=15843