Feature/bcss 20622 oracle markdown improvements (#92)

<!-- markdownlint-disable-next-line first-line-heading -->
## Description

Changing the markdown doc to address feedback found during reviews.

## Context

Allows for easier understanding of how and when to use the utility.

## Type of changes

<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply. -->

- [x ] Refactoring (non-breaking change)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would change existing
functionality)
- [ ] Bug fix (non-breaking change which fixes an issue)

## Checklist

<!-- Go over all the following points, and put an `x` in all the boxes
that apply. -->

- [x ] I am familiar with the [contributing
guidelines](https://github.com/nhs-england-tools/playwright-python-blueprint/blob/main/CONTRIBUTING.md)
- [ x] I have followed the code style of the project
- [ ] I have added tests to cover my changes (where appropriate)
- [x ] I have updated the documentation accordingly
- [ ] This PR is a result of pair or mob programming

---

## Sensitive Information Declaration

To ensure the utmost confidentiality and protect your and others
privacy, we kindly ask you to NOT including [PII (Personal Identifiable
Information) / PID (Personal Identifiable
Data)](https://digital.nhs.uk/data-and-information/keeping-data-safe-and-benefitting-the-public)
or any other sensitive data in this PR (Pull Request) and the codebase
changes. We will remove any PR that do contain any sensitive
information. We really appreciate your cooperation in this matter.

- [x ] I confirm that neither PII/PID nor sensitive data are included in
this PR and the codebase changes.

Author: mepr1

docs/utility-guides/Oracle.md

@@ -1,15 +1,25 @@
 # Utility Guide: Oracle
 
-The Oracle Utility can be used to run SQL queries or stored procedures on the Oracle database.
+The Oracle Utility provides an easy way to interact with an Oracle database directly from your Playwright test suite.It can be used to run SQL queries or stored procedures on the Oracle database.
+
+## When and Why to Use the Oracle Utility
+
+You might need to use this utility in scenarios such as:
+
+- To run SQL queries or stored procedures on the Oracle database.
+- Verifying that data is correctly written to or updated in the database after a workflow is completed in your application.
 
 ## Table of Contents
 
 - [Utility Guide: Oracle](#utility-guide-oracle)
+  - [When and Why to Use the Oracle Utility](#when-and-why-to-use-the-oracle-utility)
   - [Table of Contents](#table-of-contents)
   - [Using the Oracle Utility](#using-the-oracle-utility)
   - [Required arguments](#required-arguments)
+  - [Oracle Utility Methods](#oracle-utility-methods)
   - [Example usage](#example-usage)
   - [Oracle Specific Functions](#oracle-specific-functions)
+  - [How to Add New Oracle-Specific Functions](#how-to-add-new-oracle-specific-functions)
   - [Example Usage](#example-usage-1)
 
 ## Using the Oracle Utility
@@ -22,29 +32,45 @@ The functions in this class require different arguments.<br>
 Look at the docstrings for each function to see what arguments are required.<br>
 The docstrings also specify when arguments are optional, and what the default values are when no argument is provided.
 
-## Example usage
+## Oracle Utility Methods
+
+**The main methods provided by OracleDB are:**
 
-    from utils.oracle.oracle import OracleDB
+- **connect_to_db(self)**: Connects to the Oracle database using credentials from environment variables.
+- **disconnect_from_db(self, conn)**: Closes the provided Oracle database connection.
+- **execute_query(self, query, params=None)**: Executes a SQL query with optional parameters and returns the results as a pandas DataFrame.
+- **execute_stored_procedure(self, `procedure_name`, params=None)**: Executes a named stored procedure with optional parameters.
+- **exec_bcss_timed_events(self, nhs_number_df)**: Runs the `bcss_timed_events` stored procedure for each NHS number provided in a DataFrame.
+- **get_subject_id_from_nhs_number(self, nhs_number)**: Retrieves the `subject_screening_id` for a given NHS number.
 
-    def test_oracle_query() -> None:
+For full implementation details, see utils/oracle/oracle.py.
 
-        query = """select column_a,
-        column_b,
-        column_c
-        from example_table
-        where condition_1 = :condition1
-        and condition_2 = :condition2"""
+## Example usage
 
-        params = {
+```python
+from utils.oracle.oracle import OracleDB
+
+def test_oracle_query() -> None:
+    query = """
+    SELECT column_a,
+           column_b,
+           column_c
+    FROM example_table
+    WHERE condition_1 = :condition1
+      AND condition_2 = :condition2
+    """
+    params = {
         "condition1": 101,
         "condition2": 202,
-        }
-
-        result_df = OracleDB().execute_query(query, params)
+    }
+    result_df = OracleDB().execute_query(query, params)
+    print(result_df)
 
-    def run_stored_procedure() -> None:
+def run_stored_procedure() -> None:
+    OracleDB().execute_stored_procedure("bcss_timed_events")
+```
 
-        OracleDB().execute_stored_procedure("bcss_timed_events")
+---
 
 ## Oracle Specific Functions
 
@@ -53,15 +79,33 @@ These are all stored in one location to make it easier to edit the query at a la
 
 Common values are placed in the `SqlQueryValues` class to avoid repeating the same values in the queries.
 
-## Example Usage
+## How to Add New Oracle-Specific Functions
 
-    from oracle.oracle import OracleDB
+- Define a new function in `utils/oracle/oracle_specific_functions.py`.
+- Create your SQL query, `parameterizing` as needed.
+- Call the  relevant methods from the oracle `util` based on your needs (e.g., `execute_query`, stored procedure methods, etc.).
+- Return the result in the appropriate format for your function.
+- Document the function with a clear docstring.
 
-    def example_query() -> pd.DataFrame:
-
-        example_df = OracleDB().execute_query(
-            f"""subject_nhs_number
-        from ep_subject_episode_t
-        where se.latest_event_status_id in ({SqlQueryValues.S10_EVENT_STATUS}, {SqlQueryValues.S19_EVENT_STATUS})""")
+## Example Usage
 
-        return example_df
+```python
+from utils.oracle.oracle import OracleDB
+
+def example_query() -> pd.DataFrame:
+    """
+    Example function to demonstrate OracleDB usage for querying subject NHS numbers.
+    Returns:
+        pd.DataFrame: Query results as a pandas DataFrame.
+    """
+    example_df = OracleDB().execute_query(
+        f"""subject_nhs_number
+    from ep_subject_episode_t
+    where se.latest_event_status_id in ({SqlQueryValues.S10_EVENT_STATUS}, {SqlQueryValues.S19_EVENT_STATUS})""")
+
+    return example_df
+```
+
+> **Note:**<br>
+> The Oracle utility and its helper functions are available under utils/oracle/.<br>
+> See the source code for more details.