Add better documentation for examples

Author: shanejbrown

examples/README.rst

@@ -2,36 +2,50 @@
 Buildrunner Example Configurations
 ==================================
 
-This directory contains several example configuration files for Buildrunner.
+This directory contains example configuration files for Buildrunner, demonstrating various use cases and best practices. These examples serve as references for users looking to configure and execute Buildrunner effectively.
 
 Running Buildrunner with Example Configuration Files
-""""""""""""""""""""""""""""""""""""""""""""""""""""
+====================================================
 
-To run Buildrunner using the example configuration files, execute the following commands from
-the top-level directory within the Buildrunner repository.
+To run Buildrunner using an example configuration file, follow these steps from the root directory of the Buildrunner repository:
 
+1. **Navigate to the Buildrunner repository directory.**
 
-1. **Install Buildrunner:**
+2. **Install Buildrunner (Recommended: Use a Virtual Environment)**
+
+   It is recommended to install Buildrunner within a virtual environment to avoid conflicts with system-wide dependencies.
 
    .. code-block:: sh
 
       pip install .
 
-2. **Run Buildrunner:**
+3. **Execute Buildrunner with a specified configuration file:**
 
    .. code-block:: sh
 
-      ./bin/buildrunner -f examples/<name_of_config_file>
+      ./bin/buildrunner -f examples/<path-to-config-file>
 
    For example:
 
    .. code-block:: sh
 
       ./bin/buildrunner -f examples/configs/build/basic/buildrunner.yaml
 
-Adding New Example Configuration Files
-""""""""""""""""""""""""""""""""""""""
-To add a new example configuration file, add a new file under the `examples/` directory. The new file should end with ``buildrunner.yaml`` to ensure that
-the unit tests can automatically detect and run the new example configuration file. The new file should contain a valid Buildrunner configuration and should be able
-to run successfully using the instructions provided above with no other manual setup. If needed, add a README.rst file to the same directory as the configuration file
-to provide additional information. Any additional files needed by the configuration should be colocated with the configuration file.
+Adding a New Example Configuration File
+=======================================
+
+To contribute a new example configuration file, adhere to the following guidelines:
+
+1. **File Location & Naming**
+   - Place the new file in the ``examples/`` directory.
+   - Ensure the filename ends with ``.buildrunner.yaml`` to allow automatic detection and execution by unit tests.
+
+2. **Configuration Validity**
+   - The configuration file must contain a valid Buildrunner configuration.
+   - It should execute successfully using the standard instructions provided in this repository without requiring any manual intervention.
+
+3. **Documentation & Additional Files**
+   - If necessary, include a ``README.rst`` file in the same directory as the configuration file to provide additional details or instructions.
+   - Any supporting files required for the configuration should be placed alongside the configuration file.
+
+Following these best practices ensures consistency, maintainability, and ease of use for all contributors and users.  

examples/build/basic/buildrunner.yaml

@@ -1,3 +1,4 @@
+# Basic buildrunner configuration to build a simple Docker image.
 steps:
   simple-build-step:
     build:

examples/run/basic/buildrunner.yaml

@@ -1,3 +1,4 @@
+# Basic buildrunner configuration to run a simple Docker image.
 steps:
   simple-run-step:
     run: