Closes #89: Update README to better explain use-case. (#90)

README.md

@@ -7,11 +7,40 @@
 [![Codacy Quality](https://api.codacy.com/project/badge/Grade/f8600bde4f684cf98b8255c814d753c3)](https://www.codacy.com/manual/swichers/acsf-client)
 [![Codacy Coverage](https://api.codacy.com/project/badge/Coverage/f8600bde4f684cf98b8255c814d753c3)](https://www.codacy.com/manual/swichers/acsf-client)
 
-Acquia Cloud Site Factory is a hosting platform provided by Acquia. As part of that platform an API is provided for developers to use. The goal of this library is to wrap that API in such a way that it becomes trivial to leverage it in PHP applications.
+Acquia Cloud Site Factory is a hosting platform provided by Acquia. The goal of this library is to wrap the ACSF API in such a way that it becomes trivial to leverage it in PHP applications. This library is a significant boon when it comes to streamlining interactions with ACSF. Usage of this library will, among other things, facilitate a much quicker and less error prone deployment process.
+
+**Caution:** Test coverage in this library is around validation of calls to the API, and is not testing interaction with the actual ACSF API. Not all wrapped endpoints have been validated as properly implemented, and live calls to the API may have unexpected results. Review all scripts and calls for proper behavior before executing against a live environment.
+
+## Why use this project?
+
+You may already be familiar with projects such as [ACSF Tools](https://github.com/acquia/acsf-tools) or the [Acquia CLI](https://github.com/acquia/cli) and be wondering what this project has to offer over those.
+
+| Feature                               | ACSF Client | ACSF Tools | Acquia CLI |
+| ------------------------------------- | :---------: | :--------: | :--------: |
+| PHP library                           |      ✅     |     ❌     |     ❌     |
+| Supports Site Factory                 |      ✅     |     ✅     |     ❌     |
+| Supports Acquia Cloud                 |      ❌     |     ❌     |     ✅     |
+| Complete implementation of ACSF API   |      ✅     |     ❌     |     ❌     |
+| Complete implementation of Cloud API  |      ❌     |     ❌     |     ✅     |
+| Can bundle with codebase              |      ✅     |     ✅     |     ❌     |
+| Can be standalone                     |      ✅     |     ✅     |     ✅     |
+| Designed for scripting                |      ✅     |     ❌     |     ❌     |
+| Designed for specific tasks           |      ❌     |     ✅     |     ❌     |
+
+The primary use case for this project is creating custom PHP scripts for automating your development and management workflows within ACSF. Anything that you can do within the ACSF UI should be accomplishable through this library.
 
 ![Backporting sites to dev demonstration](https://user-images.githubusercontent.com/5890607/66103462-b6579d00-e56a-11e9-88c3-bc10936afb94.gif)
 
-**Caution:** Test coverage in this library is around validation of calls to the API, and is not testing interaction with the actual ACSF API. Not all wrapped endpoints have been validated as properly implemented, and live calls to the API may have unexpected results. Review all scripts and calls for proper behavior before executing against a live environment.
+Common tasks that you can use this library to automate:
+
+* Regular complete backups with custom names
+* Regular backup pruning for backups meeting certain criteria
+* Bbackports/staging to lower environments along with code deploys
+* Production deployments, including backups, backports, and deployments
+* Recreating domains on lower environments after backports
+* Starting a deployment from your CI system
+
+The [examples](examples/) folder contains several scripts that show some common tasks. They can serve as a starting point to build much more complex workflows custom tailored to your project.
 
 ## Installation
 
@@ -29,7 +58,7 @@ composer require swichers/acsf-client
 
 ## Usage
 
-Example scripts are available in the [examples](examples/) folder.
+Many starter scripts are available in the [examples](examples/) folder.
 
 ```php
 <?php declare(strict_types=1);
@@ -45,6 +74,9 @@ Example scripts are available in the [examples](examples/) folder.
     'environment' => 'live',
   ];
 
+  // There are multiple ways to create a client, including from
+  // environment variables (recommended). View the ClientFactory
+  // class for details.
   $client = ClientFactory::createFromArray($base_config);
 
   // Check the service status.

examples/README.md

@@ -1,34 +1,38 @@
 # Library Usage Examples
 
-This folder contains some examples of how to use the library to script ACSF 
-deployments and associated tasks. To use these examples copy the `.env.dist`
-file to `.env` in this folder. Then edit and configure each value in that file.
-
+This folder contains some examples of how to use the library to script ACSF  deployments and associated tasks. To use these examples copy the `.env.dist` file to `.env` in this folder. Then edit and configure each value in that file.
+
 ```sh
 cp ../.env.dist .env
 ```
 
-## Files
+The provided scripts allow you to perform many of the common tasks you might need right out of the box, but the real power in this library comes from using these scripts as a starting point for your own more complex scripts.
+
+## Examples provided
 
 ### backport.php
 
 Usage: `php backport.php test tags/2.7.0-beta.1-build`
 
-Copies the production environment down to the given environment, and then
-deploys the tag or branch provided.
+Copies the production environment down to the given environment, and then deploys the tag or branch provided.
 
 ### backup.php
 
 Usage: `php backup.php live`
 
 Creates a backup of each site on the given environment.
 
+### cc.php
+
+Usage: `php cc.php uat`
+
+Runs the ACSF cache clear process on the given environment.
+
 ### deploy.php
 
 Usage: `php deploy.php live tags/2.7.0-beta.1-build`
 
-Deploys a new tag or branch to the target environment. Creates a backup in
-the process if the target environment is `live`.
+Deploys a new tag or branch to the target environment. Creates a backup in the process if the target environment is `live`.
 
 ### deploy-uat.php
 
@@ -44,5 +48,4 @@ Redeploys the currently checked out code on top of itself.
 
 ### simple.php
 
-A simple script to demonstrate how to backport and deploy code with minimal
-options set.
+A simple script to demonstrate how to backport and deploy code with minimal options set.