Preliminary chapter selection
brson opened this issue · 0 comments
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 inauthors.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
- 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
-
&
vs.ref
in Patterns - Holy
std::borrow::Cow
- Concurrency
- Fearless Concurrency with Rust (brson)
- How Rust Achieves Thread Safety (brson)
- Defaulting to Thread-safety: Closures and Concurrency
- Some Notes on
Send
andSync
- Niko's Rayon Trilogy
- Traits
- Abstraction Without Overhead (brson)
- Going Down the Rabbit Hole with Rust Traits
- Huon's Trait Object Quadrilogy
- Rust's Built-in Traits, the When, How & Why (brson)
- Rust Traits for Developer Friendly Libraries
- The Rust Language
unsafe
Rust- 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 - Gankro's Collections Trilogy
- 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 - Rust + Nix = Easier Unix Systems Programming
- The Rust Toolbox
- Async I/O
- Culture
- Cheat Sheets - Can these be modified for the book?
- Additional Reading - Don't include directly, but may be worth linking.
- 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
- Rustic Bits
- Mapping Over Arrays
- Rust for Functional Programmers
- From &str to Cow
- Graydon's Lists
- 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