address review comments and refactoring

docs/usage/installation.md

@@ -1,17 +1,17 @@
-# Installing IronCore
+# Installing Ironcore
 
 ## Requirements
 
 * `go` >= 1.20
-* `git`, `make` and `kubectl`
+* `git`, `make`, and `kubectl`
 * [Kustomize](https://kustomize.io/)
 * Access to a Kubernetes cluster ([Minikube](https://minikube.sigs.k8s.io/docs/), [kind](https://kind.sigs.k8s.io/) or a real cluster)
 
 ## Clone the Repository
 
-To bring up and install the `ironcore` project, you first need to clone the repository.
+To bring up and install the `Ironcore` project, you first need to clone the repository.
 
-```shell
+``` shell
 git clone [email protected]:ironcore-dev/ironcore.git
 cd ironcore
 ```
@@ -20,41 +20,41 @@ cd ironcore
 
 If there is no [cert-manager](https://cert-manager.io/docs/) present in the cluster it needs to be installed.
 
-```shell
+``` shell
 kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.2/cert-manager.yaml
 ```
 
 ## Install APIs into the Cluster
 
-Your Kubernetes API server needs to know about the APIs which come with the `ironcore` project. To install the APIs into your cluster, run
+Your Kubernetes API server needs to know about the APIs that come with the `Ironcore` project. To install the APIs into your cluster, run
 
-```shell
+``` shell
 make install
 ```
 
-**Note**: This requires the `APISERVER_IMG` (Makefile default set to `apiserver`) to be pullable from your kubernetes
-cluster. For local development with `kind`, a make target that builds and loads the api server image and then applies
+**Note**: This requires the `APISERVER_IMG` (Makefile default set to `apiserver`) to be pullable from your Kubernetes
+cluster. For local development with `kind`, a make target that builds and loads the API server image and then applies
 the manifests is available via
 
-```shell
+``` shell
 make kind-install
 ```
 
-**Note**: In case that there are multiple environments running, ensure that `kind get clusters` is pointing to the
+**Note**: In case multiple environments running, ensure that `kind get clusters` is pointing to the
 default kind cluster.
 
 ## Deploy the Controller Manager
 
-The controller manager can be started via the following command
+The controller manager can be started via the following command.
 
-```shell
+``` shell
 make kind-deploy
 ```
-## validate
+## Validate
 
-Make sure you have all the below pods running
+Make sure you have all the below pods running.
 
-```shell
+``` shell
 $ kubectl get po -n ironcore-system
 NAME                                           READY   STATUS    RESTARTS       AGE
 ironcore-apiserver-85995846f9-47247            1/1     Running   0              136m
@@ -67,14 +67,14 @@ ironcore-etcd-0                                1/1     Running   0
 The `config/samples` folder contains samples for all APIs supported by this project. You can apply any of the samples by
 running
 
-```shell
+``` shell
 kubectl apply -f config/samples/SOME_RESOURCE.yaml
 ```
 
 ## Cleanup
 
-To remove the APIs from your cluster, simply run
+To remove the APIs from your cluster, simply run.
 
-```shell
+``` shell
 make uninstall
 ```

docs/usage/storage/bucket.md

@@ -1,8 +1,9 @@
 # Bucket
-A `bucket` in `ironcore` refers to a storage resource that organizes and manages data, similar to the concept of buckets in cloud storage services like Amazon S3. Buckets serve as containers for storing objects, such as files or data blobs, and is crucial for managing storage workloads.
+A `Bucket` in `Ironcore` refers to a storage resource that organizes and manages data, similar to the concept of buckets in cloud storage services like Amazon S3. Buckets are containers for storing objects, such as files or data blobs, and are crucial for managing storage workloads.
 
 # Example Bucket Resource
-An example of how to define a `bucket` resource in `ironcore`
+An example of how to define a `Bucket` resource in `Ironcore`
+
 ```
 apiVersion: storage.ironcore.dev/v1alpha1
 kind: Bucket
@@ -11,35 +12,35 @@ metadata:
 spec:
   bucketClassRef:
     name: bucketclass-sample
-  # bucketPoolRef:
-  #   name: bucketpool-sample
+#  bucketPoolRef:
+#    name: bucketpool-sample
 ```
 
 # Key Fields:
 - `bucketClassRef`(`string`): 
-    - Mandatory field
-    - `BucketClassRef` is the BucketClass of a bucket
+  - Mandatory field
+  - `BucketClassRef` is the BucketClass of a bucket
 
 - `bucketPoolRef`(`string`):
-    - Optional field
-    -  `bucketPoolRef` indicates which BucketPool to use for the bucket, if not specified the controller itself picks the available bucketPool
+  - Optional field
+  -  `bucketPoolRef` indicates which BucketPool to use for the bucket, if not specified the controller itself picks the available bucketPool
 
 
 # Usage
-- **Data Storage**: Use buckets to store and organize data blobs, files, or any object-based data.
+- **Data Storage**: Use `Buckets` to store and organize data blobs, files, or any object-based data.
 
 - **Multi-Tenant Workloads**: Leverage buckets for isolated and secure data storage in multi-tenant environments by using separate BucketClass or BucketPool references.
 
-- **Secure Access**: Buckets store access credentials securely in their status. Applications can retrieve access details via Kubernetes secrets.
+- **Secure Access**: Buckets store a reference to the `Secret` securely in their status, and the `Secret` has the access credentials, which applications can retrieve access details from the `Secret`.
 
 # Reconciliation Process:
 - The controller detects changes and fetches bucket details.
 
 - Creation/Update ensures the backend bucket exists, metadata is synced, and credentials are updated.
 
-- The bucket will automatically sync with the backend storage system, Updates Bucket's state (e.g., `Available`, `Pending`, or `Error`) in the bucket's status.
+- The bucket will automatically sync with the backend storage system, and update the Bucket's state (e.g., `Available`, `Pending`, or `Error`) in the bucket's status.
 
-- Access details and credentials will be managed securely and updated in the bucket status.
+- Access details and credentials will be managed securely using Kubernetes `Secret` and the bucket status will track a reference to the `Secret`.
 
 - During deletion, resources will be cleaned up gracefully without manual intervention.
 

docs/usage/storage/bucketclass.md

@@ -1,8 +1,8 @@
 # BucketClass
-A BucketClass is a concept used to define and manage different types of storage buckets, typically based on resource capabilities
+A `BucketClass` is a concept used to define and manage different types of storage buckets, typically based on resource capabilities. It is conceptually similar to Kubernetes `StorageClass`, enabling users to specify the desired properties for an Ironcore `Bucket` resource creation.
 
 # Example BucketClass Resource
-An example of how to define a bucketClass resource
+An example of how to define a `BucketClass` resource in `Ironcore`
 
 ```
 apiVersion: storage.ironcore.dev/v1alpha1
@@ -15,21 +15,25 @@ capabilities:
 ```
 
 # Key Fields:
-- capabilities: Capabilities has `tps` and `iops` fields which need to specified, it's a mandatory field,
-  - tps(`string`): The `tps` represents trasactions per second
 
-  - iops(`string`):  `iops` is the number of input/output operations a storage device can complete per second.
+- `capabilities`: Capabilities has `tps` and `iops` fields which need to be specified, it's a mandatory field,
+  - `tps`(`string`): The `tps` represents transactions per second.
+
+  - `iops`(`string`):  `iops` is the number of input/output operations a storage device can complete per second.
 
 # Usage
-- **BucketClass Definition**: Create a BucketClass to set storage properties based on resource capibilities
-- **Associate with buckets**: Link a BucketClass to a Bucket using a reference in the Bucket resource.
-- **Dynamic configuration**: Update the BucketClass to modify storage properties for all its Buckets.
+
+- **BucketClass Definition**: Create a `BucketClass` to set storage properties based on resource capabilities.
+
+- **Associate with buckets**: Link a `BucketClass` to a `Bucket` using a reference in the Bucket resource.
+
+- **Dynamic configuration**: Update the `BucketClass` to modify storage properties for all its Buckets.
 
 # Reconciliation Process:
 
-- **Fetches & Validates**: Retrieves the BucketClass from the cluster and checks if it exists.
+- **Fetches & Validates**: Retrieves the `BucketClass` from the cluster and checks if it exists.
 
-- **Synchronizes State**: Keeps the BucketClass resource updated with its current state and dependencies.
+- **Synchronizes State**: Keeps the `BucketClass` resource updated with its current state and dependencies.
 
 - **Monitors Dependencies**: Watches for changes in dependent Bucket resources and reacts accordingly.
 

docs/usage/storage/bucketpool.md

@@ -1,7 +1,8 @@
 # BucketPool
-A `BucketPool` is a resource in `IronCore` that represents a pool of storage buckets managed collectively. It defines the infrastructure's storage configuration used to provision and manage buckets, ensuring resource availability and compatibility with associated `BucketClasses`.
+A `BucketPool` is a resource in `Ironcore` that represents a pool of storage buckets managed collectively. It defines the infrastructure's storage configuration used to provision and manage buckets, ensuring resource availability and compatibility with associated BucketClasses.
 
 # Example BucketPool Resource
+An example of how to define a `BucketPool` resource in `Ironcore`
 
 ```
 apiVersion: storage.ironcore.dev/v1alpha1

docs/usage/storage/volume.md

@@ -1,9 +1,9 @@
 # Volume
-The `IronCore` `Volume` is a storage abstraction provided by the `IronCore Runtime Interface` `(IRI)` service, designed to integrate with external storage backend for managing persistent storage. It acts as a managed storage unit, ensuring consistency, scalability, and compatibility with Kubernetes workloads.
-By integrating IronCore Volumes with Kubernetes, users benefit from seamless storage management, automation, and advanced features such as encryption and scalability, making it suitable for modern cloud-native and hybrid applications.
+The `Ironcore` `Volume` is a storage abstraction provided by the `Ironcore Runtime Interface` `(IRI)` service, designed to integrate with external storage backend for managing persistent storage. It acts as a managed storage unit, ensuring consistency, scalability, and compatibility with Kubernetes workloads.
+By integrating Ironcore Volumes with Kubernetes, users benefit from seamless storage management, automation, and advanced features such as encryption and scalability, making it suitable for modern cloud-native and hybrid applications.
 
 # Example Volume Resource
-An example of how to define a `volume` resource in `ironcore`
+An example of how to define a `Volume` resource in `Ironcore`
 
 ```
 apiVersion: storage.ironcore.dev/v1alpha1
@@ -21,11 +21,11 @@ spec:
 
 # Key Fields:
 
-- `volumeClassRef`(`string`): `volumeClassRef` refers to the name of an ironcore `volumeclass`( for eg: `slow`, `fast`, `super-fast` etc.) to create a volume,
+- `volumeClassRef`(`string`): `volumeClassRef` refers to the name of an Ironcore `volumeClass`( for eg: `slow`, `fast`, `super-fast` etc.) to create a volume,
 
 - `volumePoolRef` (`string`): 	`VolumePoolRef` indicates which VolumePool to use for a volume. If unset, the scheduler will figure out a suitable `VolumePoolRef`.
 
-- `resources`: Resources is a description of the volume's resources and capacity.
+- `resources`: `Resources` is a description of the volume's resources and capacity.
 
 # Reconciliation Process:
 
@@ -36,7 +36,7 @@ spec:
 - **Check IRI Volumes**: List and identify `IRI` volumes linked to the `Volume` resource.
 
 - **Create or Update Volume**:
-  - Create a new IRI volume if none exist.
+  - Create a new IRI volume if none exists.
   - Update existing IRI volumes if attributes like size or encryption need adjustments.
 
 - **Sync Status**: Reflect the IRI volume's state (e.g., Pending, Available) in the Kubernetes Volume resource's status.

docs/usage/storage/volumeclass.md

@@ -1,8 +1,8 @@
 # VolumeClass
-The `VolumeClass` in `IronCore` is a Kubernetes-like abstraction that defines a set of parameters or configurations for provisioning storage resources through the `IronCore Runtime Interface (IRI)`. It is conceptually similar to Kubernetes `StorageClass`, enabling users to specify the desired properties for an IronCore `Volume` resource creation.
+The `VolumeClass` in `Ironcore` is a Kubernetes-like abstraction that defines a set of parameters or configurations for provisioning storage resources through the `Ironcore Runtime Interface (IRI)`. It is conceptually similar to Kubernetes `StorageClass`, enabling users to specify the desired properties for an Ironcore `Volume` resource creation.
 
 # Example VolumeClass Resource
-An example of how to define a volumeClass resource
+An example of how to define a `VolumeClass` resource in `Ironcore`
 
 ```
 apiVersion: storage.ironcore.dev/v1alpha1
@@ -15,15 +15,18 @@ capabilities:
 ```
 
 # Key Fields:
-- capabilities: Capabilities has tps and iops fields which need to specified, it's a mandatory field,
-  - tps(`string`): The `tps` represents trasactions per second
+- `capabilities`: Capabilities has tps and iops fields that need to be specified, it's a mandatory field,
+  - `tps`(`string`): The `tps` represents transactions per second.
 
-  - iops(`string`):  `iops` is the number of input/output operations a storage device can complete per second.
+  - `iops`(`string`): `iops` is the number of input/output operations a storage device can complete per second.
 
 # Usage
-- **VolumeClass Definition**: Create a volumeClass to set storage properties based on resource capibilities
-- **Associate with Volume**: Link a volumeClass to a Volume using a reference in the Volume resource.
-- **Dynamic configuration**: Update the volumeClass to modify storage properties for all its Volumes.
+
+- **VolumeClass Definition**: Create a `VolumeClass` to set storage properties based on resource capabilities.
+
+- **Associate with Volume**: Link a `VolumeClass` to a `Volume` using a reference in the Volume resource.
+
+- **Dynamic configuration**: Update the `VolumeClass` to modify storage properties for all its Volumes.
 
 # Reconciliation Process:
 

docs/usage/storage/volumepool.md

@@ -1,7 +1,8 @@
 # VolumePool
-A `VolumePool` is a resource in `IronCore` that represents a pool of storage volume managed collectively. It defines the infrastructure's storage configuration used to provision and manage volumes, ensuring resource availability and compatibility with associated `VolumeClasses`.
+A `VolumePool` is a resource in `Ironcore` that represents a pool of storage volume managed collectively. It defines the infrastructure's storage configuration used to provision and manage volumes, ensuring resource availability and compatibility with associated `VolumeClasses`.
 
-# Example Volume Resource
+# Example VolumePool Resource
+An example of how to define a `VolumePool` resource in `Ironcore`
 
 ```
 apiVersion: storage.ironcore.dev/v1alpha1
@@ -18,7 +19,7 @@ spec:
 ```
 
 # Key Fields:
-- `ProviderID`(`string`):  The `providerId` helps the controller identify and communicate with the correct  storage system within the specific backened storage porvider.
+- `providerID`(`string`): The `providerId` helps the controller identify and communicate with the correct storage system within the specific backened storage porvider.
 
     for example `ironcore://shared`