docs: Update README.md and DEVELOPMENT.md

Signed-off-by: David Leong <[email protected]>

DEVELOPMENT.md

@@ -1,48 +1,37 @@
 # Development documentation
 
-This package has two active branches:
-
-- `mainline` -- For active development. This branch is not intended to be consumed by other packages. Any commit to this branch may break APIs, dependencies, and so on, and thus break any consumer without notice.
-- `release` -- The official release of the package intended for consumers. Any breaking releases will be accompanied with an increase to this package's interface version.
-
-## Build / Test / Release
-
-### Build the package
+This documentation provides guidance on developer workflows for working with the code in this repository.
 
-```bash
-hatch build
-```
+Table of Contents:
 
-### Run tests
+* [The Development Loop](#the-development-loop)
+* [Submitter Development Workflow](#submitter-development-workflow)
+* [Application Interface Adaptor Development Workflow](#application-interface-adaptor-development-workflow)
 
-```bash
-hatch run test
-```
-
-### Run linting
-
-```bash
-hatch run lint
-```
+This package has two active branches:
 
-### Run formatting
+- `mainline` -- For active development. This branch is not intended to be consumed by other packages. Any commit to this branch may break APIs, dependencies, and so on, and thus break any consumer without notice.
+- `release` -- The official release of the package intended for consumers. Any breaking releases will be accompanied with an increase to this package's interface version.
 
-```bash
-hatch run fmt
-```
 
-## Run tests for all supported Python versions
+## The Development Loop
 
-```bash
-hatch run all:test
-```
+We have configured [hatch](https://github.com/pypa/hatch) commands to support a standard development loop. You can run the following
+from any directory of this repository:
 
-## Use development Submitter in Houdini
+* `hatch build` - To build the installable Python wheel and sdist packages into the `dist/` directory.
+* `hatch run test` - To run the PyTest unit tests found in the `test/unit` directory. See [Testing](#testing).
+* `hatch run all:test` - To run the PyTest unit tests against all available supported versions of Python.
+* `hatch run lint` - To check that the package's formatting adheres to our standards.
+* `hatch run fmt` - To automatically reformat all code to adhere to our formatting standards.
+* `hatch shell` - Enter a shell environment that will have Python set up to import your development version of this package.
+* `hatch env prune` - Delete all of your isolated workspace [environments](https://hatch.pypa.io/1.12/environment/)
+   for this package.
+* `hatch run install` - A development version of the Deadline Cloud node is then available in `/out` by pressing TAB, typing `deadline`, and adding it to the network.
 
-```bash
-hatch run install
-```
-A development version of the Deadline Cloud node is then available in `/out` by pressing TAB, typing `deadline`, and adding it to the network.
+Note: Hatch uses [environments](https://hatch.pypa.io/1.12/environment/) to isolate the Python development workspace
+for this package from your system or virtual environment Python. If your build/test run is not making sense, then
+sometimes pruning (`hatch env prune`) all of these environments for the package can fix the issue.
 
 ## Submitter Development Workflow
 

README.md

@@ -4,63 +4,114 @@
 [![python](https://img.shields.io/pypi/pyversions/deadline-cloud-for-houdini.svg?style=flat)](https://pypi.python.org/pypi/deadline-cloud-for-houdini)
 [![license](https://img.shields.io/pypi/l/deadline-cloud-for-houdini.svg?style=flat)](https://github.com/aws-deadline/deadline-cloud-for-houdini/blob/mainline/LICENSE)
 
-AWS Deadline Cloud for Houdini is a python package that allows users to create [AWS Deadline Cloud][deadline-cloud] jobs from within Houdini. Using the [Open Job Description (OpenJD) Adaptor Runtime][openjd-adaptor-runtime] this package also provides a command line application that adapts Houdini's command line interface to support the [OpenJD specification][openjd].
+AWS Deadline Cloud for Houdini is a Python package that supports creating and running SideFX Houdini jobs within [AWS Deadline Cloud](deadline-cloud).
+It provides both the implementation of a Houdini plug-in for your workstation that helps you offload the computation for your rendering workloads
+to [AWS Deadline Cloud](deadline-cloud) to free up your workstation's compute for other tasks, and the implementation of a command-line
+adaptor application based on the [Open Job Description (OpenJD) Adaptor Runtime][openjd-adaptor-runtime] that improves AWS Deadline Cloud's
+ability to run Houdini efficiently on your render farm.
 
 [deadline-cloud]: https://docs.aws.amazon.com/deadline-cloud/latest/userguide/what-is-deadline-cloud.html
 [deadline-cloud-client]: https://github.com/aws-deadline/deadline-cloud
 [openjd]: https://github.com/OpenJobDescription/openjd-specifications/wiki
 [openjd-adaptor-runtime]: https://github.com/OpenJobDescription/openjd-adaptor-runtime-for-python
 [openjd-adaptor-runtime-lifecycle]: https://github.com/OpenJobDescription/openjd-adaptor-runtime-for-python/blob/release/README.md#adaptor-lifecycle
+[service-managed-fleets]: https://docs.aws.amazon.com/deadline-cloud/latest/userguide/smf-manage.html
+[default-queue-environment]: https://docs.aws.amazon.com/deadline-cloud/latest/userguide/create-queue-environment.html#conda-queue-environment
 
 ## Compatibility
 
 This library requires:
 
 1. Houdini 19.5, 20.0 or 20.5
 1. Python 3.9 or higher; and
-1. Linux, MacOS, or Windows operating system.
+1. Linux, Windows, or a macOS operating system.
 
-## Submitter
+## Versioning
+
+This package's version follows [Semantic Versioning 2.0](https://semver.org/), but is still considered to be in its 
+initial development, thus backwards incompatible versions are denoted by minor version bumps. To help illustrate how
+versions will increment during this initial development stage, they are described below:
+
+1. The MAJOR version is currently 0, indicating initial development. 
+2. The MINOR version is currently incremented when backwards incompatible changes are introduced to the public API. 
+3. The PATCH version is currently incremented when bug fixes or backwards compatible changes are introduced to the public API. 
+
+## Getting Started
+
+This Houdini integration for AWS Deadline Cloud has two components that you will need to install:
+
+1. The Houdini submitter plug-in must be installed on the workstation that you will use to submit jobs; and
+2. The Houdini adaptor must be installed on all of your AWS Deadline Cloud worker hosts that will be running the Houdini jobs that you submit.
+
+Before submitting any large, complex, or otherwise compute-heavy Houdini render jobs to your farm using the submitter and adaptor that you
+set up, we strongly recommend that you construct a simple test scene that can be rendered quickly and submit renders of that
+scene to your farm to ensure that your setup is correctly functioning.
+
+### Houdini Submitter Plug-in
 
 This package provides a Houdini ROP node that creates jobs for AWS Deadline Cloud using the [AWS Deadline Cloud client library][deadline-cloud-client]. Based on the loaded scene it determines the files required, allows the user to specify render options, and builds an [OpenJD template][openjd] that defines the workflow.
 
-## Adaptor
+To install the submitter plug-in, refer to [DEVELOPMENT.md](DEVELOPMENT.md) section `Submitter Development Workflow`. Also refer to Deadline Cloud's [documentation](https://docs.aws.amazon.com/deadline-cloud/latest/userguide/submitter.html) on how to launch and use the Houdini submitter after installation.
+
+[Houdini Render nodes (ROP)]: https://www.sidefx.com/docs/houdini/nodes/out/index.html
+[deadline-cloud-monitor-setup]: https://docs.aws.amazon.com/deadline-cloud/latest/userguide/submitter.html#install-deadline-cloud-monitor
+[aws-cli-credentials]: https://docs.aws.amazon.com/cli/v1/userguide/cli-chap-authentication.html
+
+### Houdini Adaptor
 
 The Houdini Adaptor implements the [OpenJD][openjd-adaptor-runtime] interface that allows render workloads to launch Houdini and feed it commands. This gives the following benefits:
 * a standardized render application interface,
 * sticky rendering, where the application stays open between tasks,
 * path mapping, that enables cross-platform rendering
 
-Jobs created by the submitter use this adaptor by default.
+To install, test and use a custom Houdini Adaptor, refer to [DEVELOPMENT.md](DEVELOPMENT.md) section `Application Interface Adaptor Development Workflow`
+
+Jobs on Deadline Cloud created by the submitter use a released version of this adaptor by default. 
 
-### Getting Started
+If you are using the [default Queue Environment](default-queue-environment), or an equivalent, to run your jobs, then the released build of this adaptor will be
+automatically made available to your job. Otherwise, you will need to install the adaptor. 
 
-The adaptor can be installed by the standard python packaging mechanisms:
+The release build of the Houdini adaptor can be installed by the standard python packaging mechanisms:
 ```sh
 $ pip install deadline-cloud-for-houdini
 ```
 
-After installation it can then be used as a command line tool:
+After installation, test that it has been installed properly by running the following as the same user that runs your jobs and
+that `houdini` can be run as the same user:
 ```sh
 $ houdini-openjd --help
 ```
 
-## Frequently Asked Questions
-See our [FAQ](https://github.com/aws-deadline/deadline-cloud-for-houdini/blob/release/docs/FAQ.md) for a list of frequently asked questions.
+For more information on the commands the OpenJD adaptor runtime provides, see [here][openjd-adaptor-runtime-lifecycle].
 
-## Versioning
+### Houdini Software Availability in AWS Deadline Cloud Service Managed Fleets
 
-This package's version follows [Semantic Versioning 2.0](https://semver.org/), but is still considered to be in its 
-initial development, thus backwards incompatible versions are denoted by minor version bumps. To help illustrate how
-versions will increment during this initial development stage, they are described below:
+You will need to ensure that the version of Houdini that you want to run is available on the worker host when you are using
+AWS Deadline Cloud's [Service Managed Fleets](service-managed-fleets) to run jobs;
+hosts do not have any rendering applications pre-installed. The standard way of accomplishing this is described
+[in the service documentation](https://docs.aws.amazon.com/deadline-cloud/latest/developerguide/provide-applications.html).
+You can find a list of the versions of Houdini that are available by default 
+[in the user guide](https://docs.aws.amazon.com/deadline-cloud/latest/userguide/create-queue-environment.html#conda-queue-environment)
+if you are using the default Conda queue enivonment in your setup.
 
-1. The MAJOR version is currently 0, indicating initial development. 
-2. The MINOR version is currently incremented when backwards incompatible changes are introduced to the public API. 
-3. The PATCH version is currently incremented when bug fixes or backwards compatible changes are introduced to the public API. 
+## Viewing the Job Bundle that will be submitted
+
+To submit a job, the submitter first generates a [Job Bundle](job-bundle), and then uses functionality from the
+[Deadline](deadline-cloud-client) package to submit the Job Bundle to your render farm to run. If you would like to see
+the job that will be submitted to your farm, then you can use the "Export Bundle" button in the submitter to export the
+Job Bundle to a location of your choice. If you want to submit the job from the export, rather than through the
+submitter plug-in then you can use the [Deadline Cloud application](deadline-cloud-client) to submit that bundle to your farm.
+
+[job-bundle]: https://docs.aws.amazon.com/deadline-cloud/latest/developerguide/build-job-bundle.html
 
 ## Security
 
-See [CONTRIBUTING](https://github.com/aws-deadline/deadline-cloud-for-houdini/blob/release/CONTRIBUTING.md#security-issue-notifications) for more information.
+We take all security reports seriously. When we receive such reports, we will 
+investigate and subsequently address any potential vulnerabilities as quickly 
+as possible. If you discover a potential security issue in this project, please 
+notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/)
+or directly via email to [AWS Security]([email protected]). Please do not 
+create a public GitHub issue in this project.
 
 ## Telemetry