More stuff

CONTRIBUTING.md

@@ -61,6 +61,9 @@ Don't use glob imports, even for preludes.
 
 Sort imports.
 
+Examples should be simple and obvious enough that an experienced dev
+won't need comments. Explanation should be in prose.
+
 Describe the code in prose, not in comments. Things that should be
 described include any traits imported and their methods used. Think
 about what information here supports the use case and might not be

README.md

@@ -1,39 +1,26 @@
-# Cookin' with Rust
+# A Rust Cookbook
 
-A practical guide to the Rust crate ecosystem.
+**[Read it here]**.
 
-## Recipes
+This _Rust Cookbook_ is a collection of simple examples that
-### [Byteorder](src/pages/byteorder.md) [![byteorder][byteorder-badge]][byteorder]
+demonstrate good practices to accomplish common programming tasks,
-### [File IO](src/pages/file_io.md) [![file][file-badge]][file]
+using the crates of the Rust ecosystem.
-### [Command Line Parsing](src/pages/cliparsing.md) [![clap][clap-badge]][clap]
+
-### [JSON](src/pages/json.md) [![json][json-badge]][json]
+These examples are complete, and suitable for copying directly into
-### [TOML](src/pages/toml.md) [![toml][toml-badge]][toml]
+new cargo projects. They are tested and guaranteed to work.
-### [rand](src/pages/rand.md) [![rand][rand-badge]][rand]
+
-### [rayon](src/pages/rayon.md) [![rayon][rayon-badge]][rayon]
+[Read it here]: https://brson.github.io/rust-cookbook
 
 ## Contributing
-If you'd like to make changes to the project, please see [this guide](CONTRIBUTING.md).
+
+This project is intented to be easy for new Rust programmers to
+contribute to, and an easy to way get involved with the Rust
+community. It needs and welcomes help.
+
+For details see [CONTRIBUTING.md] on GitHub.
+
+[CONTRIBUTING.md]: https://github.com/brson/rust-cookbook/blob/master/CONTRIBUTING.md
 
 ## License
 
 MIT/Apache-2.0
-
-
-<!-- Links -->
-
-[byteorder-badge]: https://img.shields.io/crates/v/byteorder.svg?label=byteorder
-[byteorder]: https://docs.rs/byteorder
-[file-badge]: https://img.shields.io/crates/v/file.svg?label=file
-[file]: https://doc.rust-lang.org/std/fs/struct.File.html
-[clap-badge]: https://img.shields.io/crates/v/clap.svg?label=clap
-[clap]: https://kbknapp.github.io/clap-rs/clap/struct.Arg.html
-[json-badge]: https://img.shields.io/crates/v/json.svg?label=json
-[json]: http://json.rs/doc/json
-[toml-badge]: https://img.shields.io/crates/v/toml.svg?label=toml
-[toml]: http://alexcrichton.com/toml-rs/toml/
-[rand-badge]: https://img.shields.io/crates/v/rand.svg?label=rand
-[rand]: https://doc.rust-lang.org/rand/rand/index.html
-[error-docs]: https://doc.rust-lang.org/book/error-handling.html
-[error-blog]: https://brson.github.io/2016/11/30/starting-with-error-chain
-[rayon-badge]: https://img.shields.io/crates/v/rayon.svg?label=rayon
-[rayon]: https://doc.rust-lang.org/rayon/rayon/index.html

src/SUMMARY.md

@@ -1,6 +1,7 @@
 # Summary
 
 [Table of Contents](intro.md)
+[About](about.md)
 [A Note About Error Handling](error_handling_note.md)
 
 - [Basics](basics.md)

src/about.md

@@ -1,4 +1,12 @@
-# A note about error handling
+# About "Cookin' with Rust"
+
+## Who this book is for
+
+## How to read this book
+
+## How to use the examples
+
+## A note about error handling
 
 Error handling in Rust is robust when done correctly, but in today's
 Rust it requires a fair bit of boilerplate. Because of this one often
@@ -89,4 +97,3 @@ Rust book][error-docs] and [this blog post][error-blog].
 
 [error-docs]: https://doc.rust-lang.org/book/error-handling.html
 [error-blog]: https://brson.github.io/2016/11/30/starting-with-error-chain
-

src/intro.md

@@ -2,11 +2,24 @@
 
 A practical guide to the Rust crate ecosystem.
 
+This _Rust Cookbook_ (a.k.a. _Cookin' with Rust_), is a collection of
+simple examples that demonstrate good practices to accomplish common
+programming tasks, using the crates of the Rust ecosystem.
 
+[Read more about _Cookin' with Rust_](about.html), including tips for
+how to read the book, how to use the examples, notes on conventions.
 
-## Recipes
+## Contributing
 
-### Basics
+This project is intented to be easy for new Rust programmers to
+contribute to, and an easy to way get involved with the Rust
+community. It needs and welcomes help.
+
+For details see [CONTRIBUTING.md] on GitHub.
+
+[CONTRIBUTING.md]: https://github.com/brson/rust-cookbook/blob/master/CONTRIBUTING.md
+
+## Basics
 
 | Recipe | Crates | Categories |
 |--------|--------|------------|
@@ -16,36 +29,25 @@ A practical guide to the Rust crate ecosystem.
 | [Generate random values on a custom type][ex-rand-custom] | [![rand-badge]][rand] | [![cat-math-badge]][cat-math] |
 | [Construct a graph of objects][ex-petgraph-basic] | [![petgraph-badge]][petgraph] | [![cat-math-badge]][cat-math] |
 
-### Serialization
+## Serialization
 
 | Recipe | Crates | Categories |
 |--------|--------|------------|
 | [Serialize and deserialize unstructured JSON][ex-json-basic] | [![json-badge]][json] | [![cat-serialization-badge]][cat-serialization] |
 | [Deserialize an unstructured TOML configuration file][ex-toml-basic] | [![toml-badge]][toml] | [![cat-serialization-badge]][cat-serialization] |
 
-### Concurrency
+## Concurrency
 
 | Recipe | Crates | Categories |
 |--------|--------|------------|
 | [Mutate the elements of an array in parallel][ex-rayon-iter-mut] | [![rayon-badge]][rayon] | [![cat-concurrency-badge]][cat-concurrency] |
 
-### Application development
+## Application development
 
 | Recipe | Crates | Categories |
 |--------|--------|------------|
 | [Parse command line arguments][ex-clap-basic] | [![clap-badge]][clap] | [![cat-app-badge]][cat-app] |
 
-## Contributing
-
-If you'd like to make changes to the project, please see [this guide](pages/contributing.html).
-
-## License
-
-MIT/Apache-2.0
-
-
-
-
 <!--
 
 Links, in a few categories. Follow the existing structure.