DIGITAL-287: Update README with suggested improvements

.lando.dist.yml

@@ -36,14 +36,11 @@ services:
         #XDEBUG_CONFIG: 'log_level=0'
 
 tooling:
-  # @todo: Convert this to a robo command and make configurable.
   export-content:
     service: appserver
+    description: Export content as configuration.
     cmd:
-      - 'rm -r web/modules/custom/bixal_default_content/content'
-      - 'drush default-content:export-references node --folder=modules/custom/bixal_default_content/content'
-      - 'drush default-content:export-references menu_link_content --folder=modules/custom/bixal_default_content/content'
-      - 'drush default-content:export-references media --folder=modules/custom/bixal_default_content/content'
+      - './robo.sh drupal-project:export-content'
   patch:
     service: appserver
     description: Apply composer patches or regenerate lock hash.

README.md

@@ -6,28 +6,96 @@ See our [CONTRIBUTING.md](CONTRIBUTING.md) for Git configuration and working wit
 
 ### Contents
 
-- [Software Requirements](#software-requirements)
-- [Getting Starting](#getting-started)
-- [Additional Reading](#additional-reading)
+- [Software requirements](#software-requirements)
+- [QuickStart installation](#quickstart-installation)
+- [Working with the codebase](#working-with-the-codebase)
+- [Basic command reference](#basic-command-reference)
+- [Additional developer documentation](#additional-developer-documentation)
 
-## Software Requirements
+## Software requirements
 
 * PHP 8.3: Used to run `./robo.sh` / `./composer.sh` tasks
 * Composer Version 2: https://getcomposer.org/, much faster to run composer locally than through docker
 * Lando: https://lando.dev/download/
 
-## Getting Started
+See our [Install Help documentation](docs/install-help.md) for a guide to installing the PHP and Composer
+requirements locally.
 
-The local environment is configured to use the [Lando Drupal Plugin](https://docs.lando.dev/plugins/drupal/getting-started.html). However, you cannot just `lando start` the first time you start the site. Instead, please `./robo.sh lando:init`. Following that, you can interact with the environment like a normal Lando site.
+## QuickStart installation
+
+The local environment is configured to use
+the [Lando Drupal Plugin](https://docs.lando.dev/plugins/drupal/getting-started.html). However, you cannot
+just `lando start` the first time you start the site.
+
+Once you have confirmed that you have PHP 8.3 and Composer 2 installed locally run the following CLI commands to get your
+site running locally.
+
+```
+composer install
+./robo.sh lando:init
+# Installing a Drupal site from config (no DB needed).
+lando si
+```
+
+Following that, you can interact with the environment like a normal Lando site using standard `lando` commands.
+
+## Working with the codebase
 
 There is some custom functionality apart from what's in the base Lando installation.
-* Installing a Drupal site from config (no DB needed): `lando si`
-* If switching to a new branch, always: `lando rebuild -y && lando si` to start off completely fresh.
+
 * See a list of shortcuts (Drush, Composer, etc.): `./robo.sh common:shortcuts-help`
-* Use `./composer.sh` instead of `composer` or `lando composer`. `./composer.sh` will cause entries `composer.log` to be made so we can replay composer commands on conflicts.
-* Sign in as admin: `./drush.sh uli`.
-* Export content as configuration `./robo.sh drupal-project:export-content`. See [Exporting Content as Configuration](#exporting-content-as-configuration).
+* When switching to a new branch, always: `lando rebuild -y && lando si` to start off completely fresh.
+* Export content as configuration `./robo.sh drupal-project:export-content`.
+  See [Exporting Content as Configuration](docs/backend#exporting-content-as-configuration).
+
+## Compiling theme assets
+
+See our [Frontend documentation](docs/frontend.md) for working with the `digital_gov` custom theme.
+
+## Basic command reference
+
+### Composer commands
+Instead of using `lando composer` we use `./composer.sh` which generate entries in `composer.log` so we can replay composer commands on conflicts.
+
+| **Command**                                  | **Use case**                  |
+|----------------------------------------------|-------------------------------|
+| `./composer.sh require drupal/<MODULE_NAME>` | Download a drupal module      |
+| `./composer.sh remove drupal/<MODULE_NAME>`  | Remove a drupal module        |
+| `./composer.sh update --lock`                | Regenerate composer lock hash |
+
+### Drush commands
+
+| **Command**       | **Use case**                 |
+|-------------------|------------------------------|
+| `lando drush cr`  | Clearing Drupal cache        |
+| `lando drush uli` | Log into Drupal as Superuser |
+| `lando drush cim` | Import Drupal configuration  |
+| `lando drush cex` | Export Drupal configuration  |
+
+### Lando commands
+
+| **Command**     | **Use case**                                         |
+|-----------------|------------------------------------------------------|
+| `lando start`   | Start the container                                  |
+| `lando stop`    | Stop the container                                   |
+| `lando rebuild` | Rebuild the container (retains your db)              |
+| `lando destroy` | Destroys container and your db (when all else fails) |
+
+### Custom Lando commands
+
+| **Command**            | **Use case**                                                                |
+|------------------------|-----------------------------------------------------------------------------|
+| `lando si`             | Install a fresh Drupal site from configuration                              |
+| `lando su`             | Run updates, import configuration, run cron, etc (Install if not installed) |
+| `lando xdebug-on`      | Enable Xdebug                                                               |
+| `lando xdebug-off`     | Disable Xdebug                                                              |
+| `lando patch`          | Apply composer patches or regenerate lock hash                              |
+| `lando be`             | Builds backend (composer) dependencies                                      |
+| `lando fe`             | Builds front end site (dependencies & compilation)                          |
+| `lando export-content` | Export content as configuration                                             |
+
+For additional details of custom lando commands review the tooling settings within the [Lando base file](.lando.dist.yml).
 
-## Additional Reading
+## Additional developer documentation
 
 Please take a look at the `./docs` directory for more information.

docs/install-help.md

@@ -0,0 +1,22 @@
+# Install PHP & Composer using homebrew
+
+## Install PHP 8.3
+Follow these steps to download php. You will download the base php package then install and reset to version 8.3.
+```
+brew install php
+brew install php@8.3
+# Change the version number in the following command to match the base php version number.
+# To find the base version number run `php -v`
+brew unlink php@8.4
+brew link php@8.3
+# Add path to zshrc for global access to 8.3 using php
+echo 'export PATH="/opt/homebrew/opt/php@8.3/bin:$PATH"' >> ~/.zshrc
+echo 'export PATH="/opt/homebrew/opt/php@8.3/sbin:$PATH"' >> ~/.zshrc
+```
+Confirm your version of php by opening a new terminal and running `php -v`.
+
+## Install Composer 2.0
+```
+brew install composer
+```
+Confirm composer version using `composer -v`.