From 446b60cdecd8323f3fb2ef42a3416c11f68e644f Mon Sep 17 00:00:00 2001
From: David Herman <david.herman@gmail.com>
Date: Wed, 10 Mar 2021 22:28:24 -0800
Subject: [PATCH 1/2] Project README and more content for the generated README.

---
 create-neon/README.md                    | 11 ++++
 create-neon/data/templates/README.md.hbs | 79 +++++++++++++++++++++++-
 2 files changed, 89 insertions(+), 1 deletion(-)
 create mode 100644 create-neon/README.md

diff --git a/create-neon/README.md b/create-neon/README.md
new file mode 100644
index 000000000..2384de5cb
--- /dev/null
+++ b/create-neon/README.md
@@ -0,0 +1,11 @@
+# Create Neon
+
+The `create-neon` tool bootstraps [Neon](https://neon-bindings.com) projects, which allows developers to build binary Node modules written in [Rust](https://www.rust-lang.org).
+
+## Usage
+
+You can conveniently use this tool with the [`npm init`](https://docs.npmjs.com/cli/v7/commands/npm-init) syntax:
+
+```sh
+$ npm init neon my-project
+```
diff --git a/create-neon/data/templates/README.md.hbs b/create-neon/data/templates/README.md.hbs
index 2b516d4dc..00bbad1e7 100644
--- a/create-neon/data/templates/README.md.hbs
+++ b/create-neon/data/templates/README.md.hbs
@@ -1,5 +1,82 @@
 # {{package.name}}
 
 {{#if package.description}}
-{{package.description}}
+*{{package.name}}:* {{package.description}}
+
 {{/if}}
+This project was bootstrapped by [create-neon](https://www.npmjs.com/package/create-neon).
+
+## Building {{package.name}}
+
+Building {{package.name}} requires a [supported version of Node and Rust](https://github.com/neon-bindings/neon#platform-support).
+
+You can build the project with npm. In the project directory, run:
+
+```sh
+$ npm install
+```
+
+## Exploring {{package.name}}
+
+After building {{package.name}}, you can explore its exports at the Node REPL:
+
+```sh
+$ npm install
+$ node
+> require('.').hello()
+"hello node"
+```
+
+## Available Scripts
+
+In the project directory, you can run:
+
+### `npm install`
+
+Builds the project from source. 
+
+### `npm test`
+
+Runs the unit tests by calling `cargo test`. You can learn more about [adding tests to your Rust code](https://doc.rust-lang.org/book/ch11-01-writing-tests.html) from the [Rust book](https://doc.rust-lang.org/book/).
+
+## Project Layout
+
+The directory structure of this project is:
+
+```
+{{package.name}}/
+├── Cargo.toml
+├── README.md
+├── index.node
+├── package.json
+└── src
+    └── lib.rs
+```
+
+### Cargo.toml
+
+The Cargo [manifest file](https://doc.rust-lang.org/cargo/reference/manifest.html), which informs the `cargo` command.
+
+### README.md
+
+This file.
+
+### index.node
+
+The binary module generated by building the project.
+
+### package.json
+
+The npm [manifest file](https://docs.npmjs.com/cli/v7/configuring-npm/package-json), which informs the `npm` command.
+
+### src/lib.rs
+
+The Rust library's main module.
+
+## Learn More
+
+To learn more about Neon, see the [Neon documentation](https://neon-bindings.com).
+
+To learn more about Rust, see the [Rust documentation](https://www.rust-lang.org).
+
+To learn more about Node, see the [Node documentation](https://nodejs.org).

From 98a84350624c4717c105efbe84029ba9691a31ec Mon Sep 17 00:00:00 2001
From: David Herman <david.herman@gmail.com>
Date: Fri, 12 Mar 2021 13:57:11 -0800
Subject: [PATCH 2/2] Explain the build process a bit more.

---
 create-neon/data/templates/README.md.hbs | 43 +++++++++++++++++++-----
 1 file changed, 35 insertions(+), 8 deletions(-)

diff --git a/create-neon/data/templates/README.md.hbs b/create-neon/data/templates/README.md.hbs
index 00bbad1e7..d08d86789 100644
--- a/create-neon/data/templates/README.md.hbs
+++ b/create-neon/data/templates/README.md.hbs
@@ -1,21 +1,33 @@
 # {{package.name}}
 
 {{#if package.description}}
-*{{package.name}}:* {{package.description}}
+**{{package.name}}:** {{package.description}}
 
 {{/if}}
 This project was bootstrapped by [create-neon](https://www.npmjs.com/package/create-neon).
 
-## Building {{package.name}}
+## Installing {{package.name}}
 
-Building {{package.name}} requires a [supported version of Node and Rust](https://github.com/neon-bindings/neon#platform-support).
+Installing {{package.name}} requires a [supported version of Node and Rust](https://github.com/neon-bindings/neon#platform-support).
 
-You can build the project with npm. In the project directory, run:
+You can install the project with npm. In the project directory, run:
 
 ```sh
 $ npm install
 ```
 
+This fully installs the project, including installing any dependencies and running the build.
+
+## Building {{package.name}}
+
+If you have already installed the project and only want to run the build, run:
+
+```sh
+$ npm run build
+```
+
+This command uses the [cargo-cp-artifact](https://github.com/neon-bindings/cargo-cp-artifact) utility to run the Rust build and copy the built library into `./index.node`.
+
 ## Exploring {{package.name}}
 
 After building {{package.name}}, you can explore its exports at the Node REPL:
@@ -33,7 +45,11 @@ In the project directory, you can run:
 
 ### `npm install`
 
-Builds the project from source. 
+Installs the project, including running `npm run build`.
+
+### `npm build`
+
+Builds the Node addon (`index.node`) from source.
 
 ### `npm test`
 
@@ -49,8 +65,9 @@ The directory structure of this project is:
 ├── README.md
 ├── index.node
 ├── package.json
-└── src
-    └── lib.rs
+├── src/
+|   └── lib.rs
+└── target/
 ```
 
 ### Cargo.toml
@@ -63,16 +80,26 @@ This file.
 
 ### index.node
 
-The binary module generated by building the project.
+The Node addon—i.e., a binary Node module—generated by building the project. This is the main module for this package, as dictated by the `"main"` key in `package.json`.
+
+Under the hood, a [Node addon](https://nodejs.org/api/addons.html) is a [dynamically-linked shared object](https://en.wikipedia.org/wiki/Library_(computing)#Shared_libraries). The `"build"` script produces this file by copying it from within the `target/` directory, which is where the Rust build produces the shared object.
 
 ### package.json
 
 The npm [manifest file](https://docs.npmjs.com/cli/v7/configuring-npm/package-json), which informs the `npm` command.
 
+### src/
+
+The directory tree containing the Rust source code for the project.
+
 ### src/lib.rs
 
 The Rust library's main module.
 
+### target/
+
+Binary artifacts generated by the Rust build.
+
 ## Learn More
 
 To learn more about Neon, see the [Neon documentation](https://neon-bindings.com).