Merge pull request #704 from CaroMac/prereqs

Restructure of getting started

src/data/nav.yaml

@@ -1,9 +1,9 @@
-#
-# Copyright contributors to the Galasa project
-#
-# SPDX-License-Identifier: EPL-2.0
-#
-
+#
+# Copyright contributors to the Galasa project
+#
+# SPDX-License-Identifier: EPL-2.0
+#
+
 - sections:
     - title: Releases
       root: /releases/
@@ -28,14 +28,18 @@
     - title: Docs
       root: /docs/
       items:
-        - title: Introduction and architecture
+        - title: Galasa Architecture
+          path: /docs/architecture
+        - title: Installing options
           path: /docs/
         - title: Getting started using the Galasa CLI
           path: /docs/cli-command-reference/cli-command-reference
-          items:
+          items: 
+            - title: Installing the Galasa CLI
+              path: /docs/cli-command-reference/installing-cli-tool
             - title: Initialising your local environment
               path: /docs/initialising-home-folder 
-            - title: Creating a project
+            - title: Creating a project using the CLI
               path: /docs/writing-own-tests/setting-up-galasa-project
             - title: Running a test locally
               path: /docs/cli-command-reference/cli-runs-submit-local
@@ -50,6 +54,8 @@
               path: /docs/getting-started/installing-offline
             - title: Exploring Galasa SimBank
               path: /docs/getting-started/simbank
+            - title: Creating a project using Eclipse
+              path: /docs/running-simbank-tests/setting-up-galasa-project-eclipse
         - title: Running the supplied SimBank tests
           path: /docs/running-simbank-tests
           items:

src/markdown-pages/Galasa_automation.md

@@ -59,5 +59,5 @@ Tests written for Galasa can be run locally on your computer for manual debuggin
 <b>Environment-agnostic capabilities:</b>
 
 -  Tests can be run against multiple environments as code progresses through release stages.
--  The Galasa test engine allows tests to run locally for easier development and debugging, as well as in the Galasa ecosystem for production testing at scale.
+-  The Galasa test engine allows tests to run locally for easier development and debugging, as well as in the Galasa Ecosystem for production testing at scale.
 </details>

src/markdown-pages/about_Galasa.md

@@ -32,7 +32,7 @@ Galasa simplifies testing in such an environment. The following diagram shows an
 
 This sophisticated solution requires end-to-end integration testing of an application that runs on different platforms (z/OS and Cloud) and uses different technologies (a 3270 emulator, JCL batch job and Selenium Web Driver). 
 
-When run inside a [Galasa ecosystem](/docs/ecosystem), a Galasa test can be invoked from an IDE or as part of a CI/CD pipeline. The Galasa framework initializes the test environment, creates valid test data, runs the test and validates the test output. As all test results and artifacts are stored in one location, it's easy to generate reports and diagnose the cause of any failures.
+When run inside a [Galasa Ecosystem](/docs/ecosystem), a Galasa test can be invoked from an IDE or as part of a CI/CD pipeline. The Galasa framework initializes the test environment, creates valid test data, runs the test and validates the test output. As all test results and artifacts are stored in one location, it's easy to generate reports and diagnose the cause of any failures.
 
 
 ## Use Galasa to help you to: 

src/markdown-pages/doc_root.md

@@ -1,45 +1,23 @@
 ---
 path: "/docs"
-title: "Introduction"
+title: "Installing options"
 ---
-This hub page contains links to the main Galasa documentation. To get going with Galasa as quickly as possible, explore the [Getting started](/docs/getting-started) section. Read on to learn a little about Galasa's architecture first.
 
-# Galasa's architecture
-At its top level, Galasa decomposes into three major components:
+There are a few options available when installing Galasa. Prerequisites vary, depending on the option that is chosen. 
 
-* The underlying core Galasa framework
-* A collection of Managers 
-* A test runner
+You can install Galasa for using in the command-line, for using in Eclipse, or for sharing with your department (using the Galasa zipped distribution). 
 
-*Galasa's key components (not all Managers are currently implemented)*
-![Galasa architecture](galasa-architecture-framework.svg)
+There are benefits of installing Galasa for using in the command-line. Much of the configuration set-up that is required is done for you automatically by scripts, so less manual intervention is needed. You can then import the configuration into an IDE of your choice, rather than having to use Eclipse.
 
-## 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. 
+If you are using only Eclipse for your IDE, do not have restricted internet access and want to use open-source Galasa you might choose to install the Galasa Eclipse plug-in directly from the external update site for using in Eclipse. 
 
-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.
+If you do not have access to Maven Central, Eclipse Marketplace, and Docker Hub from your company network, you can use the Galasa zipped distribution. 
 
-It is unlikely that you will need to change the framework or test runner code during the normal range of testing activities. 
 
-For more information about the benefits of using a framework for your automated testing, see the [Benefits of Galasa](../about/automation) section.
+## Next steps
 
-## 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.
+If you are installing Galasa for using in the command-line, follow the instructions in the [Getting started using the CLI](/docs/cli-command-reference/cli-command-reference) documentation.
 
-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.
+If you are installing Galasa for using in the Eclipse, or if you are installing the zipped distribution of Galasa, follow the instructions in the [Getting started using Eclipse](/docs/getting-started) documentation. 
 
-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.
-
-Three types of Manager are delivered with Galasa:
-
-* *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 *CICSManager*, *WMQManager* 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.
-
-### 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](/docs/managers) that are currently available or planned for future releases is available in the Managers topic.
-
-## The test runner
-Under the direction of the core framework, the Galasa test runner is responsible for actually executing your tests.
+To find out about the architecture of Galasa and some of its key components, take a look at the [Galasa architecture](/docs/architecture) documentation. 

src/markdown-pages/docs/architecture.md

@@ -0,0 +1,46 @@
+---
+path: "/docs/architecture"
+title: "Architecture"
+---
+
+To get going with Galasa as quickly as possible, explore the [Installing options](/docs) section. Read on to learn a little about Galasa's architecture and key components.
+
+# Galasa's architecture
+At its top level, Galasa decomposes into three major components:
+
+* The underlying core Galasa framework
+* A collection of Managers 
+* A test runner
+
+*Galasa's key components (not all Managers are currently implemented)*
+![Galasa architecture](../galasa-architecture-framework.svg)
+
+## 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.
+
+It is unlikely that you will need to change the framework or test runner code during the normal range of testing activities. 
+
+For more information about the benefits of using a framework for your automated testing, see the [Benefits of Galasa](../about/automation) section.
+
+## 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.
+
+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.
+
+Three types of Manager are delivered with Galasa:
+
+* *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 *CICSManager*, *WMQManager* 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.
+
+### 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](/docs/managers) that are currently available or planned for future releases is available in the Managers topic.
+
+## The test runner
+Under the direction of the core framework, the Galasa test runner is responsible for actually executing your tests.

src/markdown-pages/docs/cli-command-reference/cli-command-reference.md

@@ -3,50 +3,8 @@ path: "/docs/cli-command-reference/cli-command-reference"
 title: "Getting started using the Galasa CLI"
 ---
 
-Use the Galasa command line interface (Galasa CLI) to help you complete tasks, for example, submitting and monitoring Galasa test runs. You can use the same set of Galasa CLI commands to run a given task, regardless of the technology that you are using. 
-
-## Installing the CLI tool
-
-You can [download the CLI tool](https://github.com/galasa-dev/cli/releases) from the _cli_ repository in GitHub. 
-
-The following versions of the Galasa CLI tool are available to download for different operating systems:
-
-| Operating system  |  Download  |
-| :---- | :-------- | 
-| MacOSX  | galasactl-darwin-x86_64 |
-| MacOSX  | galasactl-darwin-arm64 |
-| Linux 64-bit x86 | galasactl-linux-x86_64 | 
-| Linux arm64 | galasactl-linux-arm64 | 
-| zLinux  | galasactl-linux-s390x | 
-| Windows | galasactl-windows-x86_64.exe | 
-
-
-## Getting started 
-
-Complete the following steps to start running the Galasa CLI tool:
-
-On Mac or Unix:
-
-1. Find out the architecture of your machine by typing the command `uname -m` into your terminal. 
-2. Download the appropriate binary for your machine architecture and re-name it to `galasactl`.
-3. Add `galasactl` to your PATH to enable the tool to be called from the command line without having to specify the path to the directory in which it is stored. For example, ```export PATH=${PATH}:/my/folder/containing/galasactl```.
-4. Set execute permission on the binary by running the `chmod +x galasactl` command in the directory containing `galasactl`.
-5. Set permission to open the CLI tool by running the `spctl --add galasactl` command in the directory containing `galasactl`. You are prompted by a security panel asking you to log in to show that you are issuing the command.
-
-You are now able to run Galasa CLI commands from the command line. 
-
-
-On Windows (Powershell)
-
-1. Download the binary and re-name it to `galasactl`.
-2. Add `galasactl` to your PATH to enable the tool to be called from the command line without having to specify the path to the directory in which it is stored. 
-3. Open `cmd.exe` and type `start galasactl.exe` in the directory containing `galasactl`.
-
-You are now able to run Galasa CLI commands from the command line. 
-
-
-*Note:* It is useful to put `galasactl` in your PATH to enable the Galasa CLI tool to be called from any directory. If you are using a Mac, you can find `PATH`, and the directories stored within it, by entering the command `echo $PATH | tr ":" "\n"` in your terminal. If you are using Windows, type the command `C:\> echo %PATH%`. You can then either add the binary into a directory that is already in your PATH, or add a new directory containing the tool to your PATH.
 
+If you are installing Galasa for using in the command-line, you can use the Galasa command line interface tool (Galasa CLI) to interact with Galasa to complete tasks, for example, submitting and monitoring Galasa test runs. You can use the same set of Galasa CLI commands to run a given task, regardless of the technology that you are using. 
 
 
 ## About Galasa CLI commands
@@ -63,26 +21,25 @@ Go programs can sometimes struggle to resolve DNS names, especially when a worki
 
 ## Getting help
 
-Use the following command to get more information about the command and command options, including default values.
+Once you have installed the Galasa CLI, you can use the following command to get more information about the command and command options, including default values.
 
 ```
 galasactl --help
 ```
 
-Use the following options to send logging information to a file. Any folder that is referrenced must exist. Existing files are overwritten. Specify `-` to log to `stderr`. The default is no logging.
+Use the `--log` option to send logging information to a file. Any folder that is referenced must exist. Existing files are overwritten. Specify `-` to log to `stderr`. The default is no logging.
 
 ```
 galasactl --log <logFilePath>  
 ```  
 
 ## Errors
 
-You can view a list of error messages that can be output by the galasactl tool in the <a href="https://github.com/galasa-dev/cli/blob/main/docs/generated/errors-list.md" target="_blank"> Galasa cli repository</a> in GitHub.
-
-
-
+You can view a list of error messages that can be generated by the galasactl tool in the <a href="https://github.com/galasa-dev/cli/blob/main/docs/generated/errors-list.md" target="_blank"> Galasa cli repository</a> in GitHub.
 
 
 
+## Next steps
 
+To install Galasa for using in the command line, follow the instructions in the [Installing the Galasa CLI](/docs/cli-command-reference/installing-cli-tool) documentation.