Merge pull request #55 from bcgov-nr/docs/readmeImprovement

docs: improve readme and clarify local usage

README.md

@@ -1,60 +1,78 @@
 # NR Repository Composer
 
-NR Repository Composer provides convenient way to launch generators to scaffold applications using NRIDS tooling and deployment pipelines. The generators are created using [Yeoman](http://yeoman.io) and packaged into a docker container for running on a developer's machine.
+NR Repository Composer provides convenient way to launch generators to scaffold applications using NRIDS tooling and deployment pipelines. The generators are created using [Yeoman](http://yeoman.io). For distribution, it is packaged into a docker container for running on a developer's machine.
 
 # Prerequisites
 
-## Podman or Docker
+There are two ways to run the composer.
 
-The generators are easiest to run by installing Podman or Docker so that you can use the prebuilt container (ghcr.io/bcgov-nr/nr-repository-composer).
+## Run using a Container
+
+You will need to install one of the following.
 
 * [Podman](https://podman.io)
 * [Docker](https://www.docker.com)
 
-# Usage - Podman
-
-First, open a terminal and change the current working directory to the root of the checked out repository that you wish to scaffold. The examples map the current working directory to the '/src' directory inside of the container which is the directory the generator outputs to.
+The generators are easiest to run by installing Podman or Docker so that you can use the prebuilt container (ghcr.io/bcgov-nr/nr-repository-composer).
 
-It is recommended that you run the generators only on a clean repository.
+It is recommended that users running Windows install the command locally or use Podman. Docker cannot modify the file permissions correctly on mounted volumes. As such, the example commands will not work.
 
-The generator will output a file saving your answers. This is useful if you want to rerun the generator in the future to take advantage of any updated workflows.
+## Run using a local install
 
-This command will run the 'gh-maven-build' generator:
+You will need to install node and clone this repository.
 
-```
-podman run --rm -it -v ${PWD}:/src --userns keep-id ghcr.io/bcgov-nr/nr-repository-composer:latest -- nr-repository-composer:gh-maven-build
-```
+* [Node 20](https://nodejs.org/en)
 
-Note: You can run the command with or without the generator specified.
+The tool is build using [Yeoman](http://yeoman.io) which is a JavaScript library. You do not need to install Yoeman.
 
-# Usage - Local
+Install the dependencies with `npm ci` and link it with `npm link` so Yoeman can find the local installation. If you make code changes, you do not need the re-link it.
 
 ```bash
 npm ci
 npm link
 ```
 
-Then, run a generator:
+# Usage
+
+First, open a terminal and change the current working directory to the root of the checked out repository that you wish to scaffold. It is recommended that you run the generators only on a clean repository.
+
+The generators will output a file to save your answers and will update any `app-config.yaml` catalogue file. This is useful if you want to rerun the generator in the future to take advantage of any updated workflows.
+
+The example command will run the 'gh-maven-build' generator.
+
+### Container
+
+```
+podman run --rm -it -v ${PWD}:/src --userns keep-id ghcr.io/bcgov-nr/nr-repository-composer:latest -- nr-repository-composer:gh-maven-build
+```
+```
+docker run --rm -it -v ${PWD}:/src ghcr.io/bcgov-nr/nr-repository-composer:latest -- nr-repository-composer:gh-maven-build
+```
+
+The examples map the current working directory to the '/src' directory inside of the container which is the directory the generator outputs to.
+
+### Local
 
 ```bash
 npx yo nr-repository-composer:gh-maven-build
 ```
 
 ## Generators
 
-### Github Maven Build: gh-maven-build
+All generators are built to be rerun multiple times.
 
-The generator, gh-maven-build, generates the CI workflow and NR Broker intention files for building Java/Tomcat with Maven in GitHub.
+### Backstage: backstage
+
+The generator, backstage, generates a `app-config.yaml` catalogue file.
 
-Answer the prompts:
+### Github Maven Build: gh-maven-build
 
-1. Project name (e.g. my-app)
-2. Service name (e.g. my-app-war)
-3. OpenShift Artifactory project (default: cc20)
-4. Maven pom file root (default: repository root)
+The generator, gh-maven-build, generates the CI workflow and NR Broker intention files for building Java/Tomcat with Maven in GitHub.
 
 The generated files will appear in your .github/workflows and .jenkins directories.
 
+The option `--promptless` can be used with this command to attempt to run it without prompting for responses. It will attempt to only use information stored in your `app-config.yaml`. This option can be combined with `--force` which will let Yoeman automatically overwrite any existing files.
+
 # Developing Generators
 
 ## Requirements