suggest R Markdown hunks approach for README and vignette (#161)

Author: maelle

appendix.Rmd

@@ -4,6 +4,8 @@
 
 ## dev
 
+* 2019-06-17, add suggestion to use R Markdown hunks approach when the README and the vignette share content.
+
 * 2019-06-17, add mention of central building of documentation websites.
 
 * 019-06-13, add explanations of CRAN checks.

pkg_building.Rmd

@@ -136,7 +136,7 @@ can be found at *link*".
 
 * The package should contain top-level documentation for `?foobar`, (or ``?`foobar-package` `` if there is a naming conflict). Optionally, you can use	both `?foobar` and ``?`foobar-package` `` for the package level manual file, using `@aliases` roxygen tag. `usethis::use_package_doc()` adds the template for the top-level documentation.
 
-* The package should contain at least one vignette providing a substantial coverage of package functions, illustrating realistic use cases and how functions are intended to interact. If the package is small, the vignette and the README can have the same content. 
+* The package should contain at least one vignette providing a substantial coverage of package functions, illustrating realistic use cases and how functions are intended to interact. If the package is small, the vignette and the README may have very similar content. In that case, instead of maintaining these separately, we suggest an approach such as [using R Markdown hunks, relying on knitr use of child documents so you can store the re-used parts in a folder in vignettes/, and call them from both the README and the vignette](https://www.garrickadenbuie.com/blog/dry-vignette-and-readme/). 
 
 * As is the case for a README, top-level documentation or vignettes may be the first point of entry for users. If your package connects to a data source or online service, or wraps other software, it should provide enough information for users to understand the nature of the data, service, or software, and provide links to other relevant data and documentation.  For instance, a vignette intro or documentation should not merely read, "Provides access to GooberDB," but also include, "..., an online repository of Goober sightings in South America.  More information about GooberDB, and documentation of database structure and metadata can be found at *link*". Any vignette should outline prerequisite knowledge to be able to understand the vignette upfront.