Merge pull request #94 from theohbrothers/docs/readme-improve-documen…

…tation-in-various-sections

Docs (readme): Improve documentation in various sections

README.md

@@ -24,7 +24,7 @@ git clone https://github.com/theohbrothers/PSRepositoryReleaseManager.git --recu
 
 ### Submodule
 
-`PSRepositoryReleaseManager` can be used as submodule together with provided CI [remote template(s)](#ci-files).
+`PSRepositoryReleaseManager` can be used as submodule together with provided [CI remote template(s)](#ci-remote-templates).
 
 #### Main project structure
 
@@ -53,7 +53,7 @@ git --git-dir build/PSRepositoryReleaseManager/.git checkout vx.x.x
 git commit -am 'Add submodule PSRepositoryReleaseManager vx.x.x'
 ```
 
-#### CI files
+#### CI remote templates
 
 Decide on which CI provider to use in your main project based on those supported by this project. Then setup the CI file(s) for your main project, referencing relevant CI remote template(s) of this project from your main project's CI file(s).
 
@@ -83,15 +83,15 @@ The project provides a set of [entrypoint scripts](src/scripts/ci) for generatin
 
 The entrypoint script [`Invoke-Generate.ps1`](src/scripts/ci/Invoke-Generate.ps1) is used to generate release notes for any local git repository. To do so, simply define applicable [environment variables](#environment-variables) before executing the entrypoint script.
 
-The project also includes [`.vscode/tasks.json`](.vscode/tasks.json) which allows invocation of `Invoke-Generate.ps1` via [*Build Tasks*](https://code.visualstudio.com/docs/editor/tasks) in [VSCode](https://code.visualstudio.com/). Simply execute the relevant build task while entering custom or default values per variable prompt.
+The project also includes [`.vscode/tasks.json`](.vscode/tasks.json) which allows execution of `Invoke-Generate.ps1` via [*Build Tasks*](https://code.visualstudio.com/docs/editor/tasks) in [VSCode](https://code.visualstudio.com/). Simply execute the relevant build task while entering custom or default values per variable prompt.
 
 ##### Variants
 
 The names of all available release notes variants that can be chosen from can be found in the module's [`generate/variants`](src/PSRepositoryReleaseManager/generate/variants) directory, and goes by the convention `<VariantName>.ps1`.
 
 ##### Valid tags
 
-At present, the generating of release notes is only possible for tags following the format `MAJOR.MINOR.PATCH`, prepended with a lowercase `v`:
+At present, generating of release notes is only possible for tags following the format `MAJOR.MINOR.PATCH`, prepended with a lowercase `v`:
 
 ```shell
 # Valid tags
@@ -165,21 +165,21 @@ pwsh -c './PSRepositoryReleaseManager/src/scripts/ci/Invoke-Release.ps1'
 
 **Note:** Ensure the environment variable [`GITHUB_API_TOKEN`](#github-api-token) is defined prior to creating releases.
 
-Sample CI files demonstrating this approach can be found [here](docs/samples/ci/github/generic).
+Sample CI files demonstrating use of this approach can be found [here](docs/samples/ci/github/generic).
 
 #### via Submodule and CI templates
 
 ##### Generating release notes
 
-To generate release notes, reference the appropriate `generate.yml` entrypoint CI template provided by this project from your CI file. The **generate** step can also be customized through provided [parameters](docs/samples/ci/azure-pipelines/custom/azure-pipelines.generate-params.yml#L4-#L7).
+To generate release notes, reference the appropriate [`generate.yml`](templates/azure-pipelines/entrypoint) entrypoint CI remote template provided by this project from your main project's CI file. The `generate.yml` templates also support the following [parameters](docs/samples/ci/azure-pipelines/custom/azure-pipelines.generate-params.yml#L4-#L7) for customizing the generation of release notes.
 
 Generation of release notes is presently *limited* to the module's [valid tags pattern](#valid-tags).
 
 ##### Creating releases
 
-**Note:** Ensure your main project's CI file(s) and/or settings are configured to run CI jobs for tag refs.
+**Note:** Ensure your main project's CI file(s) and/or settings are configured to run CI jobs for tag refs, and that the environment variable [`GITHUB_API_TOKEN`](#github-api-token) is defined prior to creating releases.
 
-To create releases, reference the appropriate `release.yml` entrypoint CI template provided by this project from your CI file. The **release** step can also be customized through provided [parameters](docs/samples/ci/azure-pipelines/custom/azure-pipelines.release-params.yml#L4-#L21).
+To create releases, reference the appropriate [`release.yml`](templates/azure-pipelines/entrypoint) entrypoint CI remote template provided by this project from your main project's CI file. The `release.yml` templates also support the following [parameters](docs/samples/ci/azure-pipelines/custom/azure-pipelines.release-params.yml#L4-#L21) for customizing the creation of releases.
 
 Releases supports all tag refs. Tags *need not* follow [Semantic Versioning](https://semver.org/) though the convention is recommended.
 
@@ -213,4 +213,4 @@ git commit -am 'Bump PSRepositoryReleaseManager to vx.x.x'
 ## Best practices
 
 - Use only tag refs of `PSRepositoryReleaseManager` in your main project.
-- For using the [submodule and CI templates](#via-submodule-and-ci-templates) approach, ensure your main project's CI file(s) is configured to use the CI templates of `PSRepositoryReleaseManager` and that the ref used matches that of the `PSRepositoryReleaseManager` submodule used in your main project.
+- If using the project [via Submodule and CI templates](#via-submodule-and-ci-templates), ensure your main project's CI file(s) is configured to use a [tag ref](docs/samples/ci/azure-pipelines/generic/azure-pipelines.linux-container.yml#L19) of `PSRepositoryReleaseManager` for its CI remote templates, and that the ref matches that of the `PSRepositoryReleaseManager` submodule used in your main project.