Simplify the index page that is presented when navigating to the docs

docs/content/docs/index.md

@@ -2,46 +2,153 @@
 title: Galasa Documentation
 icon: material/book-open-variant
 ---
-
-To get going with Galasa as quickly as possible, explore the [Getting started using the Galasa CLI](./cli-command-reference/index.md) section. Read on to learn a little about Galasa's architecture and key components.
 
-# Galasa's architecture
+## Quick start
 
-At its top level, Galasa decomposes into three major components:
+New to Galasa? Follow these steps to get started:
 
-* The underlying core Galasa framework
-* A collection of Managers 
-* A test runner
+1. [Install the Galasa CLI](./cli-command-reference/installing-cli-tool.md) - Download and set up the command-line tool
+2. [Initialize your local environment](./cli-command-reference/initialising-home-folder.md) - Create the necessary folder structure
+3. [Create your first project](./cli-command-reference/setting-up-galasa-project.md) - Set up a test project
+4. [Run a test locally](./cli-command-reference/runs-submit-local.md) - Execute your first test
+
+For more detailed guidance, see the complete [Getting started guide](./cli-command-reference/index.md).
+
+## Key concepts
+
+Before diving into Galasa, familiarize yourself with these important terms:
+
+- **OBR (OSGi Bundle Repository)**: An index of test bundles that tells Galasa where tests are located
+- **CPS (Configuration Property Store)**: Stores configuration settings that control how tests run
+- **DSS (Dynamic Status Store)**: Tracks resources currently in use during test execution
+- **Manager**: A component that provides an interface to interact with a given tool or technology and can handle resource provisioning on behalf of tests
+
+# Galasa architecture
+
+Galasa has three major components that work together to execute your tests:
+
+- **The core Galasa framework** - Orchestrates all activities
+- **A collection of Managers** - Provide interfaces to tools and technologies
+- **A test runner** - Executes your test code
 
-*Galasa's key components (not all Managers are currently implemented)*
 ![Galasa architecture](./galasa-architecture-framework.png)
+/// caption
+Galasa architecture showing the framework, Managers, and test runner components
+///
 
 ## The core framework
-Galasa's core framework orchestrates all component activities, and co-ordinates with the test runner to actually execute your tests. You never have to write code to *invoke* your tests - you just write the code that defines them, as a set of one or more test classes and the methods within. 
 
-The Galasa framework automatically recognizes your test definitions, and launches the required Managers and the test runner to provision and execute them. All without you having to explicitly invoke them.
+The Galasa framework orchestrates all component activities and coordinates with the test runner to execute your tests. You write test code as a set of test classes and methods, but you do not need to write code to invoke your tests.
+
+The framework automatically recognizes your test definitions and launches the required Managers and test runner to provision and execute them. This happens without you needing to explicitly invoke them.
+
+**Key responsibilities:**
 
-It is unlikely that you will need to change the framework or test runner code during the normal range of testing activities. 
+- Discovering and loading test classes
+- Managing the test lifecycle
+- Coordinating Manager activities
+- Handling resource allocation and cleanup
+- Reporting test results
 
-For more information about the benefits of using a framework for your automated testing, see the [Benefits of Galasa](../about/automation.md) section.
+You are unlikely to need to change the framework or test runner code during normal testing activities.
+
+For more information about the benefits of using a framework for automated testing, see [Benefits of Galasa](../about/automation.md).
 
 ## Managers
-The two main purposes of a Manager are to reduce the amount of boilerplate code within a test and provide proven tool interaction code. This makes the test code simpler and easier to write, understand and maintain, as the focus of a test's development shifts to validating application changes, rather than marshalling environmental resources.
 
-Sometimes, Managers perform a range of general-purpose services, and at other times, they are much more focused. For example, the HTTPClientManager contains a wide range of facilities you might expect from a programmable HTTP client, while the Db2Manager confines its scope to a range of Db2 interactions.
+Managers are the building blocks of Galasa tests. They provide the functionality you need to interact with systems and tools.
+
+### Why use Managers?
+
+Managers serve two main purposes:
+
+1. **Reduce boilerplate code**: Managers handle repetitive setup and teardown tasks, so you can focus on writing test logic
+2. **Provide proven tool interaction code**: Managers offer reliable, tested code for interacting with systems and tools
+
+This makes test code simpler to write, understand, and maintain. You can focus on validating application changes rather than managing environmental resources.
+
+### Manager characteristics
+
+**Manager scope:** Some Managers provide general-purpose services, while others are more focused:
+
+- `HTTPClientManager` provides a wide range of HTTP client facilities for testing web services
+- `Db2Manager` focuses specifically on Db2 database interactions
+
+**Manager collaboration:** Different Managers can work together to perform tasks, sharing information and delegating work to each other. The Galasa framework coordinates this collaboration automatically.
+
+### Types of Managers
+
+Galasa delivers three types of Managers:
+
+#### Core Managers
+
+Central, fundamental Managers with wide-ranging use. These handle common operations across different platforms.
+
+**Examples:**
 
-Different Managers can collaborate with each other to perform a joint task, including sharing information and getting other Managers to complete tasks for them. This work is coordinated by the Galasa framework.
+- `zosFileManager` - z/OS file operations (create, read, write, delete files)
+- `zosBatchManager` - z/OS batch job management (submit jobs, check status)
+- `zosCommandManager` - z/OS command execution (run system commands)
 
-Three types of Manager are delivered with Galasa:
+**Use case:** Use Core Managers when you need to perform basic operations on z/OS systems, such as setting up test data files or running batch jobs.
 
-* *Core Managers*: a set of central, fundamental Managers with wide-ranging use. Examples include *zosFileManager*, *zosBatchManager* and *zosCommandManager*. These are part of the core Galasa distribution.
-* *Product Managers*: a set of Managers responsible for test interactions with specific products, for example *CICSTSManager* and *Db2Manager*. Again, some product Managers will be part of the core Galasa distribution but it is also possible that your team may write its own Manager for a specialty product used in your organization.
-* *Other, or ancillary Managers*: a set of Managers to orchestrate the integration of a range of useful software tools and components, such as *SeleniumManager*, *JMeterManager* and *DockerManager*. It is likely that you will write your own Managers to expose the services of similar tools and components used within your team.
+These are part of the core Galasa distribution.
+
+#### Product Managers
+
+Managers for interacting with specific products and applications.
+
+**Examples:**
+
+- `CICSTSManager` - CICS Transaction Server interactions (transactions, resources)
+- `Db2Manager` - Db2 database operations (queries, updates, schema management)
+
+**Use case:** Use Product Managers when testing applications that run on specific platforms like CICS or use specific databases like Db2.
+
+Some product Managers are part of the core Galasa distribution.
+
+#### Ancillary Managers
+
+Managers that integrate useful software tools and components into your tests.
+
+**Examples:**
+
+- `SeleniumManager` - Web browser automation for UI testing
+- `JMeterManager` - Performance testing and load generation
+- `DockerManager` - Container management for test environments
+
+**Use case:** Use Ancillary Managers when you need to incorporate external tools into your test workflow, such as testing web interfaces or running performance tests.
+
+Once you master the basics, you might want to write your own Managers to expose the services of similar tools and components widely used within your team.
 
 ### Application-specific Managers
-As well as consuming the services of Managers either delivered with Galasa or written by others, you may need to write a Manager specific to your application under test - an *application-specific Manager*. This is to abstract *application-specific* boilerplate functionality into a single place, removed from the tests themselves. 
 
-A [summary table describing Managers](./managers/index.md) that are currently available or planned for future releases is available in the Managers topic.
+You may need to write a Manager specific to your application under test. This allows you to abstract application-specific boilerplate functionality into a single place, separate from the tests themselves.
+
+**When to create an application-specific Manager:**
+
+- Your tests repeatedly perform the same application-specific setup
+- You have complex application interactions that would clutter test code
+- You want to share application interaction code across multiple test projects
+
+A [summary table of available Managers](./managers/index.md) lists Managers that are currently available.
 
 ## The test runner
-Under the direction of the core framework, the Galasa test runner is responsible for actually executing your tests.
+
+The test runner executes your tests under the direction of the core framework. It handles the actual test execution process, running your test methods and reporting results.
+
+**Key responsibilities:**
+
+- Loading test classes and methods
+- Executing test methods in the correct order
+- Capturing test results and artifacts
+- Handling test failures and exceptions
+- Generating test reports
+
+The test runner works seamlessly with the framework and Managers to provide a complete test execution environment.
+
+## Next steps
+
+Ready to start testing? Head to the [Getting started guide](./cli-command-reference/index.md) to begin your Galasa journey.
+
+For more background on why Galasa was created and the problems it solves, see [About Galasa](../about/index.md).

docs/mkdocs.yml

@@ -89,6 +89,7 @@ markdown_extensions:
       generic: true
   - pymdownx.betterem:
       smart_enable: all
+  - pymdownx.blocks.caption
   - pymdownx.caret
   - pymdownx.details
   - pymdownx.emoji: