Documentation restructure

README.md

@@ -1,23 +1,30 @@
+<div align="center">
+
 # EQ Author
 
+<img width="180" height="180" src="eq-author/public/android-chrome-256x256.png" alt="eq-author logo">
+
 [![Build Status](https://travis-ci.com/ONSdigital/eq-author-app.svg?branch=master)](https://travis-ci.com/ONSdigital/eq-author-app)
 [![codecov](https://codecov.io/gh/ONSdigital/eq-author-app/branch/master/graph/badge.svg)](https://codecov.io/gh/ONSdigital/eq-author-app)
-[![Codacy Badge](https://api.codacy.com/project/badge/Grade/f9cbc9e5c531436ca73ee0769a766678)](https://www.codacy.com/app/jchapman68/eq-author-app?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=ONSdigital/eq-author-app&amp;utm_campaign=Badge_Grade)
+[![Codacy Badge](https://api.codacy.com/project/badge/Grade/f9cbc9e5c531436ca73ee0769a766678)](https://www.codacy.com/app/ONSDigital/eq-author-app)
+![Snyk Vulnerabilities for GitHub Repo](https://img.shields.io/snyk/vulnerabilities/github/ONSDigital/eq-author-app.svg)
+
+![GitHub](https://img.shields.io/github/license/ONSDigital/eq-author-app.svg)
+![GitHub repo size](https://img.shields.io/github/repo-size/ONSDigital/eq-author-app.svg)
+![GitHub release](https://img.shields.io/github/release/onsdigital/eq-author-app.svg)
+
+Author is an application for building questionnaires that run on the [Survey Runner](https://github.com/ONSDigital/eq-survey-runner) platform.
 
-Author is an application for building questionnaires that run on the [Survey Runner](https://github.com/ONSDigital/eq-survey-runner) platform, and was bootstrapped with [Create React App](https://github.com/facebookincubator/create-react-app).
+</div>
 
-The project comprises of three components:
+The project is composed of three components:
 
-- [Front end](/eq-author/README.md)
-- [API](/eq-author-api/README.md)
-- [Publisher](/eq-publisher/README.md)
+- [eq-author](/eq-author/README.md) (front end)
+- [eq-author-api](/eq-author-api/README.md) (back end)
+- [eq-publisher](/eq-publisher/README.md)
 
-## Guides  
+## Guides
 
-- [Overview](/docs/OVERVIEW.md)
 - [Installation](/docs/INSTALLATION.md)
-- [Running](/docs/RUNNING.md)
-- [Testing](/docs/TESTING.md)
+- [Authentication](/docs/AUTHENTICATION.md)
 - [Debugging](/docs/DEBUGGING.md)
-- [Build](/docs/BUILD.md)
-- [Supplimentary Information](/docs/SUPPLIMENTARY-INFO.md)

docs/AUTHENTICATION.md

@@ -1,6 +1,6 @@
 # Authentication
 
-![firebase_28dp.png](firebase_28dp.png) We currently use Firebase for basic authentication requirements.
+![Firebase logo](images/firebase_logo.png) We currently use Firebase for basic authentication requirements.
 
 - Go to [Firebase](https://firebase.google.com)
 - Add a project
@@ -11,40 +11,25 @@
 - Select settings by Project Overview
 - Copy down Project ID AND API Key
 
-## eq-author
-
-The following environment variables are required for firebase:
+Note: CLI env vars taken precedence over `.env.development.local` vars. For more information about precedence of config files, see: <https://github.com/bkeepers/dotenv#what-other-env-files-can-i-use>
 
-| Name                            | Description                                                                          | Required |
-| ------------------------------- | ------------------------------------------------------------------------------------ | -------- |
-| `REACT_APP_FIREBASE_PROJECT_ID` | The project ID for your Firebase project. Can be obtained from your Firebase project |          |
-| `REACT_APP_FIREBASE_API_KEY`    | The api key for your Firebase project. Can be obtained from your Firebase project    | Yes      |
+## eq-author
 
-They should be added to an `.env.development.local` file in the eq-author sub folder:
+The following environment variables are required for eq-author:
 
 ```
-REACT_APP_FIREBASE_PROJECT_ID="ABC"
-REACT_APP_FIREBASE_API_KEY="DEF"
-```
-
-These can also be passed on command line:
-
-```bash
-REACT_APP_FIREBASE_PROJECT_ID=ABC REACT_APP_FIREBASE_API_KEY=DEF yarn start
+REACT_APP_FIREBASE_PROJECT_ID="YOUR_FIREBASE_APP_ID"
+REACT_APP_FIREBASE_API_KEY="YOUR_API_KEY"
 ```
 
-Note: CLI env vars taken precedence over `.env.development.local` vars. For more information about precedence of config files, see: <https://github.com/bkeepers/dotenv#what-other-env-files-can-i-use>
+They should be added to an `.env.development.local` file in the eq-author sub folder:
 
 ## eq-author-api
 
-The following environment variables are required for firebase:
-
-| Name                  | Description                                                                          | Required |
-| --------------------- | ------------------------------------------------------------------------------------ | -------- |
-| `FIREBASE_PROJECT_ID` | The project ID for your Firebase project. Can be obtained from your Firebase project | Yes      |
-
-They should be added to an `.env` file in the eq-author-api sub folder:
+The following environment variables are required for eq-author-api:
 
 ```
 FIREBASE_PROJECT_ID="YOUR_FIREBASE_APP_ID"
 ```
+
+They should be added to an `.env` file in the eq-author-api sub folder:

docs/DEBUGGING.md

@@ -1,38 +1,11 @@
 # Debugging (with VS Code)
 
-## Debugging app
-
 Follow [this guide](https://github.com/docker/labs/blob/83514855aff21eaed3925d1fd28091b23de0e147/developer-tools/nodejs-debugging/VSCode-README.md) to enable debugging through VS Code.
 
 If you have started the app with `docker-compose` then you can attach a debugger. This is the `launch.json` configuration you must use instead of that detailed in the guide, it will attach _to the running docker container_:
 
-### Debugging eq-author-api
-
-`launch.json`
-
-```json
-{
-  "version": "0.2.0",
-  "configurations": [
-    {
-      "name": "Attach to Container",
-      "type": "node",
-      "request": "attach",
-      "port": 5858,
-      "address": "localhost",
-      "restart": true,
-      "sourceMaps": false,
-      "localRoot": "${workspaceRoot}",
-      "remoteRoot": "/app",
-      "protocol": "inspector"
-    }
-  ]
-}
-```
-
-### Debugging eq-publisher
-
-`launch.json`
+Change the ports with the following:
+`eq-publisher` uses port `5859`, `eq-author-api` uses port `5858`
 
 ```json
 {
@@ -54,7 +27,7 @@ If you have started the app with `docker-compose` then you can attach a debugger
 }
 ```
 
-## Debugging tests
+## Debugging tests in eq-author-api
 
 Add the following to your `launch.json` configuration:
 
@@ -67,4 +40,4 @@ Add the following to your `launch.json` configuration:
 }
 ```
 
-Then start your tests [as described above](#tests). You can now start a debugging session, and pick the jest process to attach to.
+Then start your tests [as described above](#running-tests). You can now start a debugging session, and pick the jest process to attach to.

docs/INSTALLATION.md

@@ -2,16 +2,16 @@
 
 ## Prerequisites
 
-- Install [Node](https://nodejs.org/en/) using `nvm install` in each component folder.
-- Install [Yarn](https://yarnpkg.com/en/)
-- Google Chrome
+- Install [Node.js](https://nodejs.org/en/) version 10 or later.
+- Install [Node Version Manager](https://github.com/nvm-sh/nvm/blob/master/README.md)
+- Install [Yarn Dependency Manager](https://yarnpkg.com/en/docs/install)
+- Install [Google Chrome](https://www.google.com/chrome/)
+- Install [Docker](https://docs.docker.com/install/) with [Docker Compose](https://docs.docker.com/compose/install/)
 
-## Authentication
+## Setting up Authentication
 
-Follow this guide to set up [Authentication](AUTHENTICATION.md)
+Follow [this guide](AUTHENTICATION.md) to set up authentication.
 
-## Install Dependencies
+## Installing Dependencies
 
-Just run `yarn` to install all dependencies.
-
-Follow this guide for more information on installing dependencies [Yarn Guide](https://yarnpkg.com/en/docs/installing-dependencies)
+Follow [this Yarn guide](https://yarnpkg.com/en/docs/installing-dependencies) for more information on installing dependencies.