From dc581774ffa93217115e044ae9c8965e871df87b Mon Sep 17 00:00:00 2001
From: "B.Anderson" <ba1e12@srv02405.soton.ac.uk>
Date: Sun, 17 May 2020 19:22:16 +0100
Subject: [PATCH] updated template notes; now uses a table

---
 R/README.md |  5 ++++-
 template.md | 26 ++++++++++++++++----------
 2 files changed, 20 insertions(+), 11 deletions(-)

diff --git a/R/README.md b/R/README.md
index 8dda637..50a09f6 100644
--- a/R/README.md
+++ b/R/README.md
@@ -4,4 +4,7 @@
 
 The place to keep functions - see [template info](../template.md).
 
-We recommend using [roxygen](https://roxygen2.r-lib.org/) style [documentation](https://style.tidyverse.org/documentation.html).
\ No newline at end of file
+We recommend:
+
+ * keeping one function per file for easy re-location when bug fixing
+ * using [roxygen](https://roxygen2.r-lib.org/) style [documentation](https://style.tidyverse.org/documentation.html).
\ No newline at end of file
diff --git a/template.md b/template.md
index f632286..af20540 100644
--- a/template.md
+++ b/template.md
@@ -4,16 +4,22 @@ There are as many templates for (R) repos as there R users... Here's ours.
 
 We srtucture the repo as a package. We may never build it but usually we do so that the package functions are available everywhere in it
 
- * things you should touch:
-    * env.R        : where we store all the parameters that might be re-used across our repo. Such as colour defaults, data paths etc
-    * R/           : where we store functions that get built
-    * analysis/    : where we store .Rmd files and the .R scripts that call them (usually using a `drake` plan)
-    * docs/        : where we put output generated by the .R/.Rmd code. This is helpful if you are using [github/lab pages](https://guides.github.com/features/pages/). Unfortunately the University of Southampton gitlab service does not currently support this.
-    * notData/     : where we do not store data. R packages expect certain kinds of data in their 'data/' folders. Do not put your data in it. In fact we recommend **not** putting your data in your repo at all. Yes, this breaks true reproducability but there are reasons:
+Things you should touch:
+
+| Item        | Description  |
+| --- | --- |
+| **env.R**  | Where we store all the parameters that might be re-used across our repo. Such as colour defaults, data paths etc. We avoid using a project/repo level .Rprofile because it can lead to [a **lot** of confusion](https://support.rstudio.com/hc/en-us/articles/360047157094-Managing-R-with-Rprofile-Renviron-Rprofile-site-Renviron-site-rsession-conf-and-repos-conf
+) |
+|**DESCRIPTION** | But only if you use this as a tmeplate for your own repo - it is a special file for packages |
+| **R/** | Where we store functions that get built |
+| **analysis/** | Where we store .Rmd files and the .R scripts that call them (usually using a `drake` plan) |
+| **docs/** | Where we put output generated by the .R/.Rmd code. This is helpful if you are using [github/lab pages](https://guides.github.com/features/pages/). Unfortunately the University of Southampton gitlab service does not currently support this. |
+| **notData/** | Where we do not store data. R packages expect certain kinds of data in their 'data/' folders. Do not put your data in it. In fact we recommend **not** putting your data in your repo at all. Yes, this breaks true reproducability but there are reasons:
         * we often use data that is commerecial or sensitive or personal (under GDPR) - so we cannot risk that leaking out
         * we often use _very large_ datasets which most git/hub/lab services sensibly reject
-        * we often pull real time data on the fly from elsewhere so storage makes no sense
+        * we often pull real time data on the fly from elsewhere so storage makes no sense |
+
+Things you should not touch:
 
- * things you should not touch:
-    * man/          : created by building the project/package
-    * NAMESPACE     : - ditto -
\ No newline at end of file
+| **man/** | Created by building the project/package using roxygen|
+| **NAMESPACE** | - ditto -
\ No newline at end of file
-- 
GitLab