docs: update deploy.md, installation.md and usage.md

docs/docs/tutorial/deploy.md

@@ -13,6 +13,8 @@ Follow one of the approaches below:
 - [Run deploy command](#run-deploy-command) - Run a MkDocs CLI command locally to deploy.
 - [Deploy with GitHub Actions](#deploy-with-github-actions) - Use the project's CI workflow in the cloud to build and deploy to GH Pages on commits pushed to master.
 
+Then go to your repo's _Settings_ and _Pages_ then enable _GitHub Pages_ on the `gh-pages` branch's root.
+
 _Note this is for a Project Page on a subpath, you will have to make adjustments to the command below if you want an Organization or User Page on the root path._
 
 ### Run deploy command
@@ -35,14 +37,13 @@ $ mkdocs gh-deploy --strict --force
 That will do the following:
 
 1. Clean and build to `site` directory.
-2. Push to `gh-pages` branch. Note: You must _not_ edit this branch directly.
+2. Force push to `gh-pages` branch, overwriting any changes which were pushed from another build.
-3. Enable GitHub Pages if it was not yet enabled
 
-Then go to your repo on GitHub, look at the *environment* tab and click _View deployment_.
+Then go to your repo on GitHub, look at the *Environment* tab.
 
-e.g.
+When it is done building, click _View deployment_ to see your site.
 
-- [michaelcurrin.github.io/mkdocs-quickstart/](https://michaelcurrin.github.io/mkdocs-quickstart/)
+e.g. [michaelcurrin.github.io/mkdocs-quickstart/](https://michaelcurrin.github.io/mkdocs-quickstart/)
 
 See deploy options in the help:
 
@@ -56,11 +57,3 @@ $ mkdocs gh-deploy --help
 When you make changes to your docs config or the docs directory, especially editing on GitHub directly, it's often useful to have the docs site build and deploy automatically in a remote environment. This is provided for free by GitHub.
 
 See the [docs.yml](https://github.com/MichaelCurrin/mkdocs-quickstart/blob/master/.github/workflows/docs.yml) workflow provided with this project. You don't have to change anything there. The token will be generated for you by GitHub Actions.
-
-### Mixing deploy approaches
-
-Warning - even though using the `--force` flag to force push, I _still_ got an error on the CI that I need to pull in changes first. This failing state was _caused_ by doing manual local deploy.
-
-Deleting the branch and rerunning the CI fixed it.
-
-But otherwise, avoid mixing the deploy command locally and other times doing it with CI. Maybe MkDocs needs to make a fix on the force flag.

docs/docs/tutorial/installation.md

@@ -5,6 +5,7 @@
 ## Requirements
 
 - [Python 3](https://www.python.org/)
+- [Make](https://www.gnu.org/software/make/) - standard on macOS and Linux but can be installed on Windows too.
 
 
 ## Install system dependencies
@@ -35,7 +36,7 @@ $ cd mkdocs-quickstart
 
 For more info, see the [Installation](https://www.mkdocs.org/#installation) page on the MkDocs site.
 
-### Use a virtual environment
+### Install in a virtual environment
 
 Create a virtual environment at the project root - this is used to isolate project packages from the global packages.
 
@@ -49,23 +50,25 @@ Activate the environment.
 $ source venv/bin/activate
 ```
 
-Install `mkdocs` - this is covered in the project dependencies file.
+Install `mkdocs` - this is covered in the project requirements file.
 
 ```sh
 $ cd docs
-$ pip install -r requirements.txt
+$ make install
 ```
 
+Note - `mkdocs` 1.2 causes a break on force pushes, so this is excluded in the requirements. See issue [#2447](https://github.com/mkdocs/mkdocs/issues/2447).
+
 ### Install globally
 
-If you prefer to install MkDocs once and reuse it across projects, then you can install it globally.
+If you prefer to install MkDocs once and reuse it across projects, then you can install it globally instead.
 
 MkDocs is available using package managers like `apt-get`, `homebrew` and `yum`.
 
-Or you can install like this.
+Or you can install like this:
 
 ```sh
-python3 -m pip install mkdocs
+$ python3 -m pip install mkdocs
 ```
 
 If you get prompted for `sudo` use, then cancel and run again with `-U` flag for user-level install.

docs/docs/tutorial/usage.md

@@ -1,7 +1,7 @@
 # Usage
 > Build and preview a site locally
 
-Make sure to run all commands from the `docs` directory.
+Make sure to run all commands from the `docs` directory, as that is where `Makefile` is.
 
 ```sh
 $ cd docs
@@ -14,21 +14,13 @@ $ cd docs
 $ make help
 ```
 ```
-.PHONY: docs
-
 default: install
-
+all: install build
-
 h help:
-
-
 install:
-
+upgrade:
-
 s serve:
-
 b build:
-
 d deploy:
 ```
 
@@ -38,13 +30,7 @@ d deploy:
 This will build the docs in memory (not to disk) and serve an auto-reloading server.
 
 ```sh
-$ make s
+$ make serve
-```
-
-That will use `Makefile` to run the following:
-
-```sh
-$ mkdocs serve --strict
 ```
 
 Then open in your browser:
@@ -57,11 +43,5 @@ Then open in your browser:
 Build docs site to `site` directory. This is useful for a CI flow.
 
 ```sh
-$ make b
+$ make build
-```
-
-That will use `Makefile` to run the following:
-
-```sh
-$ mkdocs build --strict
 ```