Preliminary chapter selection

[Brian Anderson]

In this phase we do a quick pass over all the candidate chapters to determine if it might fit into the book. Chapters that complete this phase are not guaranteed to be in the final book; rather, it is likely that many will be cut during later editing. For each candidate chapter we first evaluate it, and if it seems promising, import it and create a PR.

If you would like to volunteer to do the initial selection on any candidate chapter, mention it in a comment below and it will be assigned to you.

Evaluation

• Is there useful content? In particular, is there content that is not already represented better in existing chapters?
• Is the text well written? Brilliant prose is a no-brainer. We want it. Average prose is also no reason to exclude a chapter, though for practical reasons we need to keep the editing required to a minimum. Poorer prose demands exceptional content.
• Is the content substantial? A short text may not be a good candidate, though short chapters with exceptional content that is not well-represented elsewhere may still be good candidates.
• Is the content likely to be obsoleted easily? Probably not a good candidate.
• Is the content too domain specific? Probably not a good candidate.
• Does the content fit into some 'theme' with other content? Look for places where we can group chapters into book sections.

If you think it may belong in the book, submit a PR. The PR doesn't need to have a detailed evaluation, but it should justify its inclusion. If in your evaluation, you think it should not be included, leave a comment here explaining why. In either case we'll check it off the list and move on. In the PR ping the author to request permission to use the work, and to clarify the license.

In your evaluations, please be constructive and sensitive to authors' feelings. The content of this book comes from many places and circumstances. Most was not written with the expectation that it would be critically scrutinized. Here is a simple guide to giving constructive feedback.

Once the PR is accepted add that chapter to the tracking issue for subsequent stages in the editorial pipeline.

Import

Importing a chapter to the book includes these steps:

• Acquire the original source and convert it to markdown. This may mean contacting the author if the source is not obviously available. In these cases you should not assume they want their text redistributed, so explain your purpose clearly.
• Create a markdown file in src/ with a name reflecting the title.
• If the source is spread across multiple blog posts, consolidate them into one, with each given their own section heading, "Part N: $subtitle".
• Add a metadata footer, following existing convention. This does not need to be complete yet, but if you have the original URL and the licensing information, you may as well include it now.
• Add the chapter in an appropriate place to SUMMARY.md.
• Add the chapter to into.md with a one-paragraph description. If the author does not have an entry in authors.md yet, you do not need to add it now.
• Run mdbook test. For any tests that fail either fix them or ignore them. We will revisit in later passes.

Candidate chapters

• Introduction
  • Understanding Over Guesswork (brson)
  • An Alternative Introduction to Rust
• Ownership
  • Where Rust Really Shines (brson)
  • Rust Means Never Having to Close a Socket
  • The Problem with Single-threaded Shared Mutability (brson)
  • Rust Ownership the Hard Way
  • Strategies for Solving "cannot move out of" Borrowing Errors
  • Interior Mutability In Rust
    • Interior mutability in Rust: what, why, how?
    • Interior mutability in Rust, part 2: thread safety
    • Interior mutability in Rust, part 3: behind the curtain
  • & vs. ref in Patterns
  • Holy std::borrow::Cow
    • Holy std::borrow::Cow!
    • Holy std::borrow::Cow Redux!
• Concurrency
  • Fearless Concurrency with Rust (brson)
  • How Rust Achieves Thread Safety (brson)
  • Defaulting to Thread-safety: Closures and Concurrency
  • Some Notes on Send and Sync
  • Niko's Rayon Trilogy
    • Rayon: Data Parallism in Rust
    • Parallel Iterators in Rust Part 1: Foundations
    • Parallel Iterators in Rust Part 2: Producers
• Traits
  • Abstraction Without Overhead (brson)
  • Going Down the Rabbit Hole with Rust Traits
  • Huon's Trait Object Quadrilogy
    • Peeking Inside Trait Objects
    • The Sized Trait
    • Object Safety
    • Where Self meets Sized: Revisiting Object Safety
  • Rust's Built-in Traits, the When, How & Why (brson)
  • Rust Traits for Developer Friendly Libraries
• The Rust Language
  • Finding Closure in Rust (brson)
  • Mixing Matching, Mutations and Moves
  • Reading Rust Function Signatures
  • Myths and Legends About Integer Overflow in Rust
  • A Practical Introduction to Rust Macros
  • Effectively Using Iterators in Rust
  • A Journey Into Iterators
  • Macros In Rust
    • Part 1
    • Part 2
    • Part 3
    • Part 4
• unsafe Rust
  • Unsafe Rust: An Intro and Open Questions
  • What Does Rust's unsafe Mean?
  • Memory Leaks are Memory Safe
  • On Reference Counting and Leaks
  • A Few More Remarks on Reference Counting and Leaks
  • Pre-pooping Your Pants With Rust
  • Tootsie-pop model
    • Unsafe Abstractions
    • The "Tootsie Pop" Model for Unsafe Code
• Rust in Practice
  • The Many Kinds of Code Reuse in Rust
  • Rust Error Handling
  • Why your first FizzBuzz implementation may not work
  • Herman Radtke's String Trilogy
    • String vs. &str in Rust Functions
    • Creating a Rust Function That Accepts String or &str
    • Creating a Rust Function That Returns String or &str
  • Gankro's Collections Trilogy
    • Rust, Lifetimes, and Collections
    • Rust, Generics, and Collections
    • Rust Collections Case Study: BTreeMap
  • Learning Rust with Entirely Too Many Linked Lists
  • Working With C Unions in Rust FFI
  • Quick tip: the #[cfg_attr] attribute
  • Using the Option Type Effectively
    • Part 1
    • Part 2
  • Rust + Nix = Easier Unix Systems Programming
• The Rust Toolbox
  • Travis on the Train
    • Helping Travis Catch the rustc Train
    • Travis on the Train, Part 2
  • Rust, Travis and GitHub Pages
  • Benchmarking In Rust
  • Profiling Rust Applications on Linux
• Async I/O
  • Getting Acquainted with mio
  • My Basic Understanding of mio and Async I/O
  • Creating a Simple Protocol With mio
  • Managing Connection State With mio
• Culture
  • Stability as a Deliverable
  • The Not Rocket Science Rule of Software Engineering
  • RIIR
    • Rewrite Everything In Rust
    • Have You Considered Rewriting it In Rust?
  • Making Your Open Source Project Newcomer Friendly
  • Rust Discovery, or: How I Figure Things Out
• Cheat Sheets - Can these be modified for the book?
  • Periodic Table of Rust Types
  • Rust String Conversions Cheat Sheet
  • Rust Iterator Cheat Sheet
• Additional Reading - Don't include directly, but may be worth linking.
  • The Book
  • The Nomicon
  • Rust By Example
  • Writing an OS in Rust
  • Rust 101
  • rustlings
  • The Little Book of Rust Macros
  • The Rust FFI Omnibus
• Uncategorized Chapters
  • Why Is A Rust Executable Large?
  • Wrapper Types in Rust: Choosing Your Guarantees
  • Rust Faster!
  • Where Are You From::from?
  • Type-level Shenanigans
    • Type-level Shenanigans
    • More Type-level Shenanigans
  • Rustic Bits
  • Mapping Over Arrays
  • Rust for Functional Programmers
  • From &str to Cow
  • Graydon's Lists
    • Five Lists of Six Things About Rust
    • Things Rust Shipped Without
  • Rust Performance: A story featuring perf and flamegraph on Linux
  • Rust Code Coverage Guide: kcov + Travis CI + Codecov / Coveralls
  • for loops in Rust
  • Convenient and idiomatic conversions in Rust
  • Using and_then and map combinators on the Rust Result Type