diff --git a/docs/detailed-usage.md b/docs/detailed-usage.md
index b06e0571..f2ace0dc 100644
--- a/docs/detailed-usage.md
+++ b/docs/detailed-usage.md
@@ -1,24 +1,26 @@
 # Detailed Nomad Pack Usage
 
-This guide will go into detail on Nomad Pack usage and commands.
+This guide goes more deeply into detail on Nomad Pack usage and commands.
 
 For an overview on basic use, see the repository [README](../README.md).
 
 For more information on writing custom packs and registries, see the [Writing Packs Guide](./writing-packs.md)
-in the repository or in the [HashiCorp Learn Guides](https://learn.hashicorp.com/nomad).
-
-<!--  TODO: Get the link to the writing own packs guide once it is up  -->
+in the repository or the [Writing Custom Packs tutorial][writing-packs-tut] at developer.hashicorp.com.
 
 ## Initialization
 
-When first using Nomad Pack, a directory at `./.nomad/packs` will be created to store information about available packs and packs in use.
+The first time you run `registry list` command, Nomad Pack will add a `nomad/packs`
+directory to your desktop user's cache directory—`$XDG_CACHE_DIR` on Linux,
+`~/Library/Caches` on macOS, `%AppData%` on Windows, etc. This folder stores
+information about cloned registries and their available packs.
 
-During initializing, Nomad Pack downloads a default registry of packs from [https://github.com/hashicorp/nomad-pack-community- registry](https://github.com/hashicorp/nomad-pack-community-registry).
+During initialization, Nomad Pack downloads a default registry of packs from the
+[Nomad Pack community registry][].
 
 The directory structure is as follows:
-
-```
-.nomad
+<!-- TODO: this will need to be trued up based on PR -->
+```plaintext
+nomad
 └── packs
     ├── <REGISTRY>
         ├── <PACK-NAME>
@@ -26,111 +28,122 @@ The directory structure is as follows:
                 ├── ...files containing pack contents...
 ```
 
-The contents of the `.nomad/pack` directory are needed for Nomad Pack to work properly,
-but users must not manually manage or change these files. Instead, use the `registry`
-commands.
+The `nomad/packs` directory's contents are managed by Nomad Pack. Users should
+not manually manage or change these files. Instead, use the `registry` commands.
 
 ## List
 
 The `list` command lists the packs available to deploy.
 
-```
-nomad-pack list
+```shell
+nomad-pack registry list
 ```
 
-This command reads from the `.nomad/packs` directory explained above.
+This command reads from the `nomad/packs` directory explained earlier.
 
-## Adding new Registries and Packs
+## Add new registries and packs
 
 The `registry` command includes several sub-commands for interacting with registries.
 
 Custom registries can be added using the `registry add` command. Any `git` based
-registry supported by [`go-getter`](https://github.com/hashicorp/go-getter) should
-work.
+registry supported by [`go-getter`][] should work.
 
-For instance, if you wanted to add the entire [Nomad Pack Community Registry](https://github.com/hashicorp/nomad-pack-community-registry),
+For instance, if you wanted to add the entire [Nomad Pack community registry][],
 you would run the following command to download the registry.
 
-```
+```shell
 nomad-pack registry add community github.com/hashicorp/nomad-pack-community-registry
 ```
 
 To add a single pack from the registry, use the `--target` flag.
 
-```
+```shell
 nomad-pack registry add community github.com/hashicorp/nomad-pack-community-registry --target=nginx
 ```
 
 To download single pack or an entire registry at a specific version/SHA, use the `--ref` flag.
 
-```
+```shell
 nomad-pack registry add community github.com/hashicorp/nomad-pack-community-registry --ref=v0.0.1
 ```
 
 To remove a registry or pack from your local cache. Use the `registry delete` command.
 This command also supports the `--target` and `--ref` flags.
 
-```
+```shell
 nomad-pack registry delete community
 ```
 
-## Render
+## Render a pack
 
-At times, you may wish to use Nomad Pack to render jobspecs, but you will not want to immediately deploy these to Nomad.
+At times, you may wish to use Nomad Pack to render job specifications, but don't
+want to immediately deploy these to Nomad.
 
-This can be useful when writing a pack, debugging deployments, integrating Nomad Pack into a CI/CD environment, or if you have another mechanism for handling Nomad deploys.
+This can be useful when writing a pack, debugging deployments, integrating Nomad
+Pack into a CI/CD environment, or if you have another mechanism for handling
+deployments to Nomad.
 
-The `render` command takes the `--var` and `--var-file` flags that `run` takes.
+Like the `run` command, the `render` command takes the `--var` and `--var-file`
+flags to provide variable values and overrides.
 
-The `--to-dir` flag determines the directory where the rendered templates will be written.
+The `--to-dir` flag determines the directory where the rendered templates will
+be written.
 
-The `--render-output-template` can be passed to additionally render the output template. Some output templates rely on a deployment for information. In these cases, the output template may not be rendered with all necessary information.
+Packs can create multiple output files. When running the `render` command
+without the `--to-dir` flag the `render` command outputs all the rendered pack
+templates to the terminal underneath their file names. When rendering a pack's
+output to disk, you should use the `--to-dir` flag.
 
-```
+The `--render-output-template` can be passed to additionally render the output
+template. Some output templates rely on a deployment for information. In these
+cases, the output template may not be rendered with all necessary information.
+
+```shell
 nomad-pack render hello-world --to-dir ./tmp --var greeting=hola --render-output-template
 ```
 
-## Run
+## Run a pack
 
 To deploy the resources in a pack to Nomad, use the `run` command.
 
-```
+```shell
 nomad-pack run hello-world
 ```
 
-By passing a `--name` value into `run`, Nomad Pack deploys each resource in the
-pack with a metadata value for "pack name". If no name is given, the pack name
-is used by default.
+<!-- TODO: awkward -->
+You can pass the `--name` flag with a value to the `run` command to override the
+default pack name. Nomad Pack deploys each resource in the pack with a metadata
+value for "pack name".
 
 This allows Nomad Pack to manage multiple deployments of the same pack.
 
-```
+```shell
 nomad-pack run hello-world --name hola-mundo
 ```
 
-It is also possible to run a local pack directly from the pack directory by passing in the directory instead of the pack name.
+It's also possible to run a local pack directly from the pack directory by passing in the directory instead of the pack name.
 
-```
+```shell
 nomad pack run .
 ```
 
-### Variables
+### Provide values for pack variables
 
 Each pack defines a set of variables that can be provided by the user. Values for variables can be passed into the `run` command using the `--var` flag.
 
-```
+```shell
 nomad-pack run hello-world --var greeting=hola
 ```
 
 Values can also be provided by passing in a variables file.
 
-```
+```shell
 nomad-pack run hello-world -f ./my-variables.hcl
 ```
 
 These files can define overrides to the variables defined in the pack.
 
-```
+```hcl
 docker_image = "hashicorp/hello-world"
 
 app_count = 3
@@ -148,110 +161,172 @@ app_resources = {
 
 To see the type and description of each variable, run the `info` command.
 
-```
+```shell
 nomad-pack info hello-world
 ```
 
-## Plan
+## Plan a pack
 
 If you do not want to immediately deploy the pack, but instead want details on how it will be deployed, run the `plan` command.
 
-This invokes Nomad in a dry-run mode using the [Nomad Plan](https://www.nomadproject.io/api-docs/jobs#create-job-plan) API endpoint.
+This invokes Nomad in a dry-run mode using the [Create Job Plan][nomad-plan] API endpoint.
 
-```
+```shell
 nomad-pack plan hello-world
 ```
 
 By passing a `--name` value into plan, Nomad Pack will look for packs deployed with that name. If no name is provided, Nomad Pack uses the pack name by default.
 
-```
+```shell
 nomad-pack plan hello-world --name hola-mundo
 ```
 
 The `plan` command takes the `--var` and `-f` flags like the `run` command.
 
-```
+```shell
 nomad-pack plan hello-world --var greeting=hallo
 ```
 
-```
+```shell
 nomad-pack plan hello-world -f ./my-variables.hcl
 ```
 
-## Status
+## Get the status of running packs
+
 If you want to see a list of the packs currently deployed (this may include packs that are stopped but not yet removed), run the `status` command.
 
-```
+```shell
 nomad-pack status
 ```
 
 To see the status of jobs running in a specific pack, use the `status` command with the pack name.
 
-```
+```shell
 nomad-pack status hello-world
 ```
 
-## Destroy
+## Stop a running pack
+
+To stop the jobs without completely removing them from Nomad, use the `stop` command.
 
-If you want to remove the resources deployed by a pack, run the `destroy` command with the pack name.
+```shell
+nomad-pack stop hola-mundo
+```
 
+If you deployed the pack with a `--name` value, you must also provide the name
+you gave the pack. For instance, to stop a `hello-world` pack having the name
+`hola-mundo`, you would run the following command.
+
+```shell
+nomad-pack stop hello-world --name hola-mundo
 ```
-nomad-pack destroy hello-world
+
+When you have deployed a pack with variable overrides that override the job name,
+you must pass in those same overrides when stopping the pack. The `hello-world`
+pack allows you to override the Nomad job name and can be used to demonstrate
+this. If you deploy it with the following command.
+
+```shell
+nomad-pack run hello-world --name hola-mundo --var job_name=spanish
 ```
 
-If you deployed the pack with a `--name` value, pass in the name you gave the pack. For instance, if you deployed with the command:
+Running the following command stops the job instance named `spanish`.
 
+```shell
+nomad-pack stop hello-world --name hola-mundo --var job_name=spanish
 ```
+
+It's also possible to deploy multiple instances of a pack using the same
+`--name` value but with different job names using variable overrides.
+For example, you can run the following commands, which will create two different
+jobs, one named "spanish" and one named "hola".
+
+```shell
+nomad-pack run hello-world --name hola-mundo --var job_name=spanish
+nomad-pack run hello-world --name hola-mundo --var job_name=hola
+```
+
+If you run the destroy command without including the variable overrides, Nomad
+Pack destroys both jobs, since by default it targets all jobs belonging to the
+specified pack and deployment name.
+
+```shell
+# This stops both jobs: "spanish" and "hola"
+nomad-pack stop hello-world --name hola-mundo
+```
+
+In this case, you must also include the variable overrides so that Nomad Pack
+targets the correct instance.
+
+```shell
+# This stops the job named "spanish"
+nomad-pack stop hello-world --name hola-mundo --var job_name=spanish
+```
+
+## Destroy a running pack
+
+If you want to purge the resources deployed by a pack, run the `destroy` command with the pack name.
+
+```shell
+nomad-pack destroy hello-world
+```
+
+If you deployed the pack with a `--name` value, pass in the name you gave the pack. For instance, if you deployed it with the following command.
+
+```shell
 nomad-pack run hello-world --name hola-mundo
 ```
 
 You would destroy the contents of that pack with the command;
 
-```
+```shell
 nomad-pack destroy hello-world --name hola-mundo
 ```
 
-If you deployed the pack with variable overrides that override the job name in a pack, pass in those same overrides. For example,
-if you deployed with the command:
+When you deploy a pack with variable overrides that override the job name, pass
+in those same overrides. The `hello-world` job is one such job. If you deploy
+it with the following command.
 
-```
+```shell
 nomad-pack run hello-world --name hola-mundo --var job_name=spanish
 ```
 
-You would destroy the contents of that pack with the command:
+You would destroy a running instance of that pack with the following command.
 
-```
+```shell
 nomad-pack destroy hello-world --name hola-mundo --var job_name=spanish
 ```
 
-It's possible to deploy multiple instances of a pack using the same `--name` value but with different job names using variable
-overrides. For example, you can run the following commands, which will create two jobs,
-one named "spanish" and one named "hola":
+It's also possible to deploy multiple instances of a pack using the same
+`--name` value but with different job names using variable overrides.
+For example, you can run the following commands, which will create two different
+jobs, one named "spanish" and one named "hola".
 
-```
+```shell
 nomad-pack run hello-world --name hola-mundo --var job_name=spanish
 nomad-pack run hello-world --name hola-mundo --var job_name=hola
 ```
 
-If you run the destroy command without including the variable overrides, the command will destroy both jobs, since by default
-nomad pack will target all jobs belonging to the specified pack and deployment name.
-```
+If you run the destroy command without including the variable overrides, Nomad
+Pack destroys both jobs, since by default it targets all jobs belonging to the
+specified pack and deployment name.
+
+```shell
 # This destroys both jobs: "spanish" and "hola"
 nomad-pack destroy hello-world --name hola-mundo
 ```
 
-If you only want to destroy one of the jobs, you need to include the variable overrides so nomad pack knows which job to target:
-```
+In this case, you must also include the variable overrides so that Nomad Pack
+targets the correct instance.
+
+```shell
 # This destroys the job named "spanish"
 nomad-pack destroy hello-world --name hola-mundo --var job_name=spanish
 ```
 
-## Stop
-
-To stop the jobs without completely removing them from Nomad completely, use the `stop` command:
-
-```
-nomad-pack stop hola-mundo
-```
-
 N.B. The `destroy` command is an alias for `stop --purge`.
+
+[Nomad Pack community registry]: https://github.com/hashicorp/nomad-pack-community-registry
+[`go-getter`]: https://github.com/hashicorp/go-getter
+[nomad-plan]: https://www.nomadproject.io/api-docs/jobs#create-job-plan
+[writing-packs-tut]: https://developer.hashicorp.com/nomad/tutorials/job-specifications/nomad-pack-writing-packs
diff --git a/docs/writing-packs.md b/docs/writing-packs.md
index 0d1477c4..a4918ec8 100644
--- a/docs/writing-packs.md
+++ b/docs/writing-packs.md
@@ -9,8 +9,6 @@ the [detailed usage documentation](./detailed-usage.md).
 
 First, make a pack registry. This will be a repository that provides the structure, templates, and metadata that define your custom packs.
 
-<!-- TODO: MAKE THE EXAMPLE REPO -->
-
 Cloning [hashicorp/example-nomad-pack-registry](https://github.com/hashicorp/example-nomad-pack-registry) can give you a head start.
 
 Each registry should have a README.md file that describes the packs in it, and
@@ -19,7 +17,7 @@ pack. Conventionally, the pack subdirectory name matches the pack name.
 
 The top level of a pack registry looks like the following:
 
-```
+```plaintext
 .
 └── README.md
 └── packs
@@ -41,22 +39,25 @@ The directory should have the following contents:
 - A `variables.hcl` file that defines the variables in a pack.
 - An optional, but _highly encouraged_ `CHANGELOG.md` file that lists changes for each version of the pack.
 - An optional `outputs.tpl` file that defines an output to be printed when a pack is deployed.
-- A `templates` subdirectory containing the HCL templates used to render the jobspec.
+- A `templates` subdirectory containing the HCL templates used to render the output files.
 
 #### metadata.hcl
 
-The `metadata.hcl` file contains important key value information regarding the pack. It contains the following blocks and their associated fields:
+The `metadata.hcl` file contains important key value information about the pack. It contains the following blocks and their associated fields:
 
-- "app {url}" - The HTTP(S) url to the homepage of the application to provide a quick reference to the documentation and help pages.
-- "pack {name}" - The name of the pack.
-- "pack {description}" - A small overview of the application that is deployed by the pack.
-- "pack {version}" - The version of the pack.
-- "dependency {name}" - The dependencies that the pack has on other packs. Multiple dependencies can be supplied.
-- "dependency {source}" - The source URL for this dependency.
+- `app`
+  - `url` - The HTTP(S) URL to the homepage of the application to provide a quick reference to the documentation and help pages.
+- `pack`
+  - `name` - The name of the pack.
+  - `description` - A small overview of the application that is deployed by the pack.
+  - `version` - The version of the pack.
+- `dependency` - The dependencies that the pack has on other packs. Multiple dependencies can be supplied.
+  - `name` - The dependencies that the pack has on other packs. Multiple dependencies can be supplied.
+  - `source` - The source URL for this dependency.
 
 An example `metadata.hcl` file:
 
-```
+```hcl
 app {
   url = "https://github.com/mikenomitch/hello_world_server"
 }
@@ -72,11 +73,11 @@ pack {
 
 The `variables.hcl` file defines the variables required to fully render and deploy all the templates found within the "templates" directory.
 
-These variables are defined using [HCL](https://github.com/hashicorp/hcl).
+These variables are defined using [HCL][].
 
 An example `variables.hcl` file:
 
-```
+```hcl
 variable "datacenters" {
   description = "A list of datacenters in the region which are eligible for task placement."
   type        = list(string)
@@ -114,7 +115,7 @@ The `outputs.tpl` is an optional file that defines an output to be printed when
 
 Output files have access to pack variables and template helper functions. A simple example:
 
-```
+```go
 Congrats on deploying [[ .nomad_pack.pack.name ]].
 
 There are [[ .hello_world.app_count ]] instances of your job now running on Nomad.
@@ -138,9 +139,9 @@ Templates are written using [Go Template Syntax](https://learn.hashicorp.com/tut
 
 Unlike default Go Template syntax, Nomad Pack uses "[[" and "]]" as delimiters.
 
-An example template using variables values from above:
+The following is an example template using variables values from earlier.
 
-```
+```hcl
 job "hello_world" {
   region      = "[[ .hello_world.region ]]"
   datacenters = [ [[ range $idx, $dc := .hello_world.datacenters ]][[if $idx]],[[end]][[ $dc | quote ]][[ end ]] ]
@@ -176,11 +177,12 @@ job "hello_world" {
 
 This is a relatively simple template that mostly sets variables.
 
-The `datacenters` value shows slightly more complex Go Template, which allows for [control structures](https://learn.hashicorp.com/tutorials/nomad/go-template-syntax#control-structure-list) like `range` and [pipelines](https://learn.hashicorp.com/tutorials/nomad/go-template-syntax#pipelines).
+The `datacenters` value demonstrates slightly more complex Go Templating, which
+allows for [control structures](https://learn.hashicorp.com/tutorials/nomad/go-template-syntax#control-structure-list) (like `range`) and [pipelines](https://learn.hashicorp.com/tutorials/nomad/go-template-syntax#pipelines).
 
 #### Template Functions
 
-To supplement the standard Go Template set of template functions, the (masterminds/sprig)[https://github.com/Masterminds/sprig] library is used. This adds helpers for various use cases such as string manipulation, cryptographics, and data conversion (for instance to and from JSON).
+To supplement the standard Go Template set of template functions, the [Masterminds/sprig](https://github.com/Masterminds/sprig) library is used. This adds helpers for various use cases such as string manipulation, cryptography, and data conversion (for instance to and from JSON).
 
 Custom Nomad-specific and debugging functions are also provided:
 
@@ -193,7 +195,7 @@ Custom Nomad-specific and debugging functions are also provided:
 
 A custom function within a template is called like any other:
 
-```
+```go
 [[ nomadRegions ]]
 [[ nomadRegions | spewDump ]]
 ```
@@ -202,12 +204,14 @@ A custom function within a template is called like any other:
 
 For complex packs, authors may want to reuse template snippets across multiple resources.
 
-For instance, if we had two jobs defined in a pack, and we knew both would re-use the same `region`
-logic for both, we could use a helper template to consolidate logic.
+For instance, suppose you have two jobs defined in your pack and both jobs reuse
+the same `region` logic. You can create a helper template to centralize that
+logic.
 
-Helper template names are prepended with an underscore "\_" and end in ".tpl". So we could define a helper called "\_region.tpl":
+Helper template names are prepended with an underscore `_` and end in `.tpl`.
+You could define a helper called "\_region.tpl" with the following code.
 
-```
+```hcl
 [[- define "region" -]]
 [[- if not (eq .hello_world.region "") -]]
 region = [[ .hello_world.region | quote]]
@@ -215,9 +219,10 @@ region = [[ .hello_world.region | quote]]
 [[- end -]]
 ```
 
-Then in the parent templates, "job_a.nomad.tpl" and "job_b.nomad.tpl", we would render to the helper template using its name:
+In the parent templates, "job_a.nomad.tpl" and "job_b.nomad.tpl", you use
+the template's name to render it in place.
 
-```
+```hcl
 job "job_a" {
   type = "service"
 
@@ -231,9 +236,9 @@ job "job_a" {
 
 Packs can depend on content from other packs.
 
-First, packs must define their dependencies in `metadata.hcl`. A pack block with a dependency would look like the following:
+First, packs must define their dependencies in `metadata.hcl`. A pack block with a dependency would look like the following.
 
-```
+```hcl
 app {
   url = "https://some-url-for-the-application.dev"
 }
@@ -249,11 +254,17 @@ dependency "demo_dep" {
 }
 ```
 
-The dependency name label *must* match the `name` property of the dependant pack, as specified in its `metadata.hcl`.
+**Note**: The dependency block's label, "demo_dep" in the previous example,
+*must* match the `name` property of the dependency pack, as specified in its
+`metadata.hcl`.
 
-This would allow templates of "simple_service" to use "demo_dep"'s helper templates in the following way:
+For packs that reuse a dependency pack, add a unique `alias` attribute inside
+each dependency block to disambiguate them.
 
-```
+This allows templates of "simple_service" to use "demo_dep"'s helper templates
+in the following way.
+
+```hcl
 [[ template "demo_dep.data" . ]]
 ```
 
@@ -266,7 +277,7 @@ directory path as the name of the pack to the `run`, `plan`, `render`, `info`,
 For instance, if your current working directory is the directory where you are
 developing your pack, and `nomad-pack` is on your path, you can run this command.
 
-```
+```shell
 nomad-pack run .
 ```
 
@@ -278,23 +289,28 @@ To use your new pack, you will likely want to publish it to the internet. Push t
 accessible by your command line tool.
 
 If you wish to share your packs, please consider adding them to the
-[Nomad Pack Community Registry](https://github.com/hashicorp/nomad-pack-community-registry)
+[Nomad Pack Community Registry][].
 
 If you don't want to host a pack registry in version control, you can work locally
-using the filesystem method.
+using the file system method.
 
-## Step Six: Deploy your Custom Pack!
+## Step Six: Deploy your Custom Pack
 
 Add your custom repository using the `nomad-pack registry add` command.
 
-```
+```shell
 nomad-pack registry add my_packs github.com/<YOUR_ORG>/<YOUR_REPO>
 ```
 
 Deploy your custom packs.
 
-```
+```shell
 nomad-pack run hello_world --var app_count=1 --registry=my_packs
 ```
 
-Congrats! You can now write custom packs for Nomad!
+Your custom pack should now be running in your Nomad cluster.
+
+## Learn More
+
+[Nomad Pack community registry]: https://github.com/hashicorp/nomad-pack-community-registry
+[HCL]: https://github.com/hashicorp/hcl
\ No newline at end of file