Merge pull request #944 from DFE-Digital/docs/update-all-documentation

Docs: update all documentation

README.md

@@ -12,7 +12,7 @@ Web application to help schools plan a technology roadmap
 
 ## Running Locally
 
-- The startup project is [./src/Dfe.PlanTech.Web](./src/Dfe.PlanTech.Web)
+- The startup project is [./src/Dfe.PlanTech.Web](./src/Dfe.PlanTech.Web) with setup guidance in the [Readme](./src/Dfe.PlanTech.Web/README.md)
 
 ## Documentation 
 

contentful/content-management/README.md

@@ -4,14 +4,18 @@ Guidance for creating, updating and deleting content programatically from conten
 
 Unfortunately the contentful-migration api does not support deleting entries, so this is something that has to be done
 with the content management api instead. Migrations, where possible, should be done with contentful-migration.
-This can be used as a fallback
+This can be used as a fallback.
+
+The project is currently separate from the content-migrations project because the contentful-migration library doesn't execute changes when the script is run, instead, it outputs a plan for the migration which you can accept or reject (similar to terraform). The contentful-management library does execute changes immediately, so would run during plan creation rather than at the intended stage. To minimise the risk of developer error, these are kept apart.
 
 ## Setup
 
 1. Setup `.env` (copy `.env.example` and setup fields as necessary)
 2. cd into the `content-management` directory
 3. run `npm install`
 
+Note that the `contentful-management` library defaults to the `master` environment if there is a typo in the environment name. This is very undesirable so `validate-environment.js` will fetch all environments from contentful and ensure that `ENVIRONMENT` is one of them.
+
 ## Usage
 
 1. Add your content update script following the convention of `YYYYMMDD-HHMM-description-of-crud-operation.js`

contentful/content-migrations/README.md

@@ -24,11 +24,6 @@ Currently migrations are run manually, there will likely be a follow on piece to
 4. This will show you a plan for the migration about to happen, type `Y/N` to confirm
 5. Re-enable the webhook
 
-## Errors
-
-In the event of an error that causes the database to be updated with incorrect content,
-you can refresh the database from contentful using the [export-processor](../export-processor/README.md)
-
 ## References
 
 This follows the guidance in the contentful documentation on [scripting migrations](https://www.contentful.com/developers/docs/tutorials/cli/scripting-migrations/)

docs/Conventions.md

@@ -30,12 +30,3 @@
     <div class="js-only">This element will be hidden by default, but made visible via JS.</div>
     ```
   - The code that unhides these elements is located in [_BodyEnd.cshtml](src/Dfe.PlanTech.Web/Views/Shared/_BodyEnd.cshtml)
-
-## EF Query Conventions
-- We use a redis cache to cache contentful requests. This is setup in [Dfe.PlanTech.Infrastructure.Redis](/src/Dfe.PlanTech.Infrastructure.Redis/).
-- Any requests to contentful should use the `GetOrCreateAysnc` method from [Dfe.PlanTech.Infrastructure.Redis/RedisCache.cs](/src/Dfe.PlanTech.Infrastructure.Redis/RedisCache.cs) to cache the result
-  - For example
-    ```csharp
-    await _cache.GetOrCreateAsync($"Page:{slug}", () => _repository.GetEntities<Page?>(options, cancellationToken))
-    ```
-- More about contentful caching is explained in [contentful redis caching documentation](docs/cms/contentful-redis-caching.md)

src/Dfe.PlanTech.Infrastructure.ServiceBus/README.md

@@ -2,7 +2,8 @@
 
 Project that handles concrete implementation of connection/usage of an Azure Service Bus.
 
-Currently used for saving CMS data in our DB. For more information check out our [Contentful documentation](/docs/cms/README.md)
+Currently used for recieving CMS updates from contentful and invalidating the relevant cache items. 
+For more information check out our [Contentful documentation](/docs/cms/README.md)
 
 ## Setup
 

src/Dfe.PlanTech.Web/README.md

@@ -12,6 +12,8 @@ Uses ASP .NET Core MVC.
 - Setup your Contentful secrets, using the instructions in the [Dfe.PlanTech.Infrastructure.Contentful](../Dfe.PlanTech.Infrastructure.Contentful/README.md) project
 - Setup your Redis connection, using the instructions in the [Dfe.PlanTech.Infrastructure.Redis](../Dfe.PlanTech.Infrastructure.Redis/README.md) project
 
+The collection of all secrets is stored in the Azure keyvault, which you can use to speed up the setup process.
+
 ## Project References
 
 - Dfe.PlanTech.Application
@@ -30,7 +32,8 @@ Uses ASP .NET Core MVC.
 ## Javascript + Styling Compiling
 
 - Uses NodeJS, with [Gulp](https://gulpjs.com/), to compile Styles and Scripts
-- Scripts are located in the `/Scripts` folder and CSS/SASS are located in the `/Styles` folder
+- Scripts are located in the [/Scripts](src/Dfe.PlanTech.Web.Node/scripts) folder and CSS/SASS are located in the [/Styles](src/Dfe.PlanTech.Web.Node/styles) folder
+- Guidance is provided in the [Readme](src/Dfe.PlanTech.Web.Node/README.md)
 
 ### NodeJS Packages Used
 
@@ -42,3 +45,8 @@ Uses ASP .NET Core MVC.
 | [gulp-csso](https://www.npmjs.com/package/gulp-csso)             | CSS minification                                   |
 | [gulp-sass](https://www.npmjs.com/package/gulp-sass)             | SASS compiling                                     |
 | [gulp-sourcemaps](https://www.npmjs.com/package/gulp-sourcemaps) | Sourcemaps creation                                |
+
+## Using a local Redis or Database instance
+
+- If you want to use a local instance of Redis, instructions are provided in the [Readme](../Dfe.PlanTech.Infrastructure.Redis/README.md))
+- If you want to use a local database, the [SeedTestData Readme](tests/Dfe.PlanTech.Web.SeedTestData/README.md) contains instructions on setting up a local test database, and changing the connection string to use it