diff --git a/README.md b/README.md
index ff1e8d1..bb0a695 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,5 @@
 # Github action to build an mkdocs site and sync it to S3 :rocket:
-This is a very simple action to make publishing a static mkdocs site even easier.
+This is a very simple action to make publishing a static [mkdocs](https://www.mkdocs.org/) site even easier.
 
 ## Usage
 ### `workflow.yml` example
@@ -30,6 +30,7 @@ jobs:
 ```
 
 The s3 command uses the raw AWS CLI so any args supported within the CLI can be passed through in the with statement above. If you are going to use the above example verbatim, be warned `--delete` **permanently deletes** files in the S3 bucket that are **not** present in the latest version of your build.
+The above example will build and deploy your site on any push to master. This means your public site in S3 should always be up to date with your Github repository mkdocs `docs` directory.
 
 ## Environment variables
 The action requires at least `AWS_S3_BUCKET`, `AWS_ACCESS_KEY_ID` & `AWS_SECRET_ACCESS_KEY`. Store these as Github secrets and not statically typed in your configuration.