Work on the (first) workflow section

vignettes.Rmd

@@ -47,27 +47,40 @@ To create your first vignette, run:
 usethis::use_vignette("my-vignette")
 ```
 
-This will:
+This does the following:
 
-1.  Create a `vignettes/` directory.
+1.  Creates a `vignettes/` directory.
 
-2.  Add the necessary dependencies to `DESCRIPTION` (i.e. it adds knitr to the `Suggests` and `VignetteBuilder` fields).
+2.  Adds the necessary dependencies to `DESCRIPTION`, i.e. adds knitr to the `VignetteBuilder` field and adds both knitr and rmarkdown to `Suggests`.
 
-3.  Draft a vignette, `vignettes/my-vignette.Rmd`.
+3.  Drafts a vignette, `vignettes/my-vignette.Rmd`.
 
-The draft vignette has been designed to remind you of the important parts of an R Markdown file.
+4.  Adds some patterns to `.gitignore` to ensure that files created as a side effect of previewing your vignettes are kept out of source control (we'll say more about this later).
+
+This draft document has been designed to remind you of the important parts of an R Markdown vignette.
 It serves as a useful reference when you're creating a new vignette.
-Once you have this file, the workflow is straightforward:
+You also call `use_vignette()` to create your second and all subsequent vignettes; it will just skip any setup that's already been done.
+
+Once you have the draft vignette, the workflow is straightforward:
+
+1.  Start adding prose and code chunks to the vignette.
+
+2.  Preview the rendered vignette.
+
+    If you're documenting parts of your package that are under active development, it is important to build the vignette with the *current* source package.
+    You need to ensure that `library(yourpackage)` loads a bleeding edge version of your package.
+    Use `devtools::build_rmd()` in this case.
+    It builds your vignette against a (temporarily installed) development version of your package.
 
-1.  Modify the vignette.
+    If it's OK to build the vignette using the most-recently-installed version of your package, it's fine to use your usual workflow for rendering `.Rmd` files.
+    For example, press Ctrl/Cmd + Shift + K (or click ![](images/knit.png){width="45"}).
 
-2.  Press Ctrl/Cmd + Shift + K (or click ![](images/knit.png){width="45"}) to knit the vignette and preview the output.
+3.  Rinse and repeat until the vignette looks the way you want.
 
-3.  This builds with the installed package --- but you probably want the dev package.
-    Use `devtools::build_rmd()`.
+If you're regularly checking your entire package (@sec-r-cmd-check), which we strongly recommend, this will also help to keep your vignettes in good working order.
+In particular, this will alert you if a vignette makes use of a package that's not a formal dependency.
 
-The check workflow, `Cmd + Shift + E`, will run the code in all vignettes.
-This is a good way to verify that you've captured all the needed dependencies.
+We're deliberately leaving one workflow issue to revisit below in SOME LATER SECTION. That's where we'll clarify the official mechanism for creating the rendered vignettes that appear in your package's bundled and installed form.
 
 ## Metadata {#vignette-metadata}