Merge pull request #37 from ukgovdatascience/bugfix-documentation

Bugfix documentation issues
best-practice-and-impact · Jul 14, 2021 · 57300c5 · 57300c5
2 parents 1e15cba + 4233f75
commit 57300c5
Show file tree

Hide file tree

Showing 6 changed files with 15 additions and 14 deletions.
diff --git a/README.md b/README.md
@@ -30,10 +30,10 @@ run the following command for the latest stable release:
 cookiecutter https://github.com/ukgovdatascience/govcookiecutter.git
 ```
 
-or for a specific branch, tag, or commit SHA `SPECIFIC`, run:
+or for a specific branch, tag, or commit SHA `{SPECIFIC}`, run:
 
 ```shell
-cookiecutter https://github.com/ukgovdatascience/govcookiecutter.git --checkout SPECIFIC
+cookiecutter https://github.com/ukgovdatascience/govcookiecutter.git --checkout {SPECIFIC}
 ```
 
 Follow the prompts; if you are asked to re-download `govcookiecutter`, input `yes`.

diff --git a/docs/README.md b/docs/README.md
@@ -18,7 +18,7 @@ make docs
 or, alternatively, run:
 
 ```shell
-sphinx-build -b linkcheck ./docs ./docs/_build
+sphinx-build -b html ./docs ./docs/_build
 ```
 
 The HTML-version of this documentation can then be viewed at `docs/_build/index.html`,

diff --git a/docs/contributing_guide/modify_govcookiecutter.md b/docs/contributing_guide/modify_govcookiecutter.md
@@ -36,7 +36,8 @@ One such extension is `jinja2_time.TimeExtension`, which is used to add the corr
 year in the `{{ cookiecutter.repo_name }}/LICENSE` file.
 
 All other keys are used to inject the user responses throughout the template. This
-happens wherever you see `{{ cookiecutter.KEY }}`, where `KEY` is the key in question.
+happens wherever you see `{{ cookiecutter.{KEY} }}`, where `{KEY}` is the key in
+question.
 
 The values in `cookiecutter.json` are the default responses, shown in squared brackets
 to the user. If the user does not enter a response, these default values are used.
@@ -82,14 +83,14 @@ Conditional files and folders are defined as `features` in the
     {
       "name": "A name",
       "description": "A description.",
-      "remove": {% if cookiecutter.KEY == VALUE %}true{% else %}false{% endif %},
+      "remove": {% if cookiecutter.{KEY} == {VALUE} %}true{% else %}false{% endif %},
       "resources": ["A", "list", "of", "files", "and/or", "folders"]
     }
   ]
 }
 ```
 
-where `KEY` and `VALUE` are `cookiecutter.json` keys and values.
+where `{KEY}` and `{VALUE}` are `cookiecutter.json` keys and values.
 
 This works by using Jinja conditional templating to either set the `remove` value to
 true or false. The post-generation hook then scans through this JSON file deleting all

diff --git a/...me }}/.govcookiecutter/organisational_frameworks/GDS/aqa/assumptions_caveats.md b/...me }}/.govcookiecutter/organisational_frameworks/GDS/aqa/assumptions_caveats.md
@@ -11,9 +11,9 @@ impact[^1]:
 
 | RAG   | Assumption quality                                                                                                              | Assumption impact                                                                           |
 |-------|---------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
-| GREEN | Reliable assumption, well understood and/or documented; anything up to a validated & recent set of actual data.                 | Marginal assumptions; their changes have no or limited impact on the outputs.               |
-| AMBER | Some evidence to support the assumption; may vary from a source with poor methodology to a good source that is a few years old. | Assumptions with a relevant, even if not critical, impact on the outputs.                   |
-| RED   | Little evidence to support the assumption; may vary from an opinion to a limited data source with poor methodology.             | Core assumptions of the analysis; the output would be drastically affected by their change. |
+| Green | Reliable assumption, well understood and/or documented; anything up to a validated & recent set of actual data.                 | Marginal assumptions; their changes have no or limited impact on the outputs.               |
+| Amber | Some evidence to support the assumption; may vary from a source with poor methodology to a good source that is a few years old. | Assumptions with a relevant, even if not critical, impact on the outputs.                   |
+| Red   | Little evidence to support the assumption; may vary from an opinion to a limited data source with poor methodology.             | Core assumptions of the analysis; the output would be drastically affected by their change. |
 
 ## Assumption 1: Insert plain English title here
 

diff --git a/...ter.repo_name }}/.govcookiecutter/organisational_frameworks/GDS/aqa/data_log.md b/...ter.repo_name }}/.govcookiecutter/organisational_frameworks/GDS/aqa/data_log.md
@@ -11,9 +11,9 @@ suitability[^1]:
 
 | RAG   | Data quality                                                                                                                                                                                 | Data suitability                                                                                                                                                                                            |
 |-------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| GREEN | Data is well understood and there are no major issues with quality. Minor issues are understood and documented.                                                                              | Data is best available for the required purpose and has been validated (for example against published statistics).                                                                                          |
-| AMBER | Data is well understood. There are quality issues (for example missing values, step changes, large number of outliers) that can be explained, documented or shown to have negligible impact. | Not the ideal data set for the analysis, but the best available at the time. Results will reflect the fact that it is not the ideal data set and it will subject to sensitivity analysis where appropriate. |
-| RED   | Data is not well understood. There are major quality issues that cannot be fully explained and/or have a significant impact on analysis outputs.                                             | There are concerns about the suitability of the data set for this application, which could negatively affect the quality and accuracy of the analysis. Its derivation / sample size is not known.           |
+| Green | Data is well understood and there are no major issues with quality. Minor issues are understood and documented.                                                                              | Data is best available for the required purpose and has been validated (for example against published statistics).                                                                                          |
+| Amber | Data is well understood. There are quality issues (for example missing values, step changes, large number of outliers) that can be explained, documented or shown to have negligible impact. | Not the ideal data set for the analysis, but the best available at the time. Results will reflect the fact that it is not the ideal data set and it will subject to sensitivity analysis where appropriate. |
+| Red   | Data is not well understood. There are major quality issues that cannot be fully explained and/or have a significant impact on analysis outputs.                                             | There are concerns about the suitability of the data set for this application, which could negatively affect the quality and accuracy of the analysis. Its derivation / sample size is not known.           |
 
 ## Source 1: Insert plain English title here
 

diff --git a/...repo_name }}/.govcookiecutter/organisational_frameworks/GDS/request_template.md b/...repo_name }}/.govcookiecutter/organisational_frameworks/GDS/request_template.md
@@ -7,12 +7,12 @@ Way](https://gds-way.cloudapps.digital/standards/pull-requests.html).
 # Checklists
 
 <!--
-These are DO-CONFIRM checklists; it CONFIRMs that you have DOne each item.
+These are do-confirm checklists; it confirms that you have DOne each item.
 
 Outstanding actions should be completed before reviewers are assigned; if actions are
 irrelevant, please try and add a comment stating why.
 
-Incomplete pull/merge requests MAY be blocked until actions are resolved, or closed at
+Incomplete pull/merge requests may be blocked until actions are resolved, or closed at
 the reviewers' discretion.
 -->