refactoring

docs/usage/compute/machine.md

@@ -1,11 +1,11 @@
 # Machine
 
 A `Machine` resource in `IronCore` is used to represent a compute resource or a virtual machine. 
-It serves as a means to configure network, storage, type of machine and other information needed to create a VM. The `MachineController` reconciler leverages this information to determine where the machine needs to be created and type of machine needs to be created along with required `Network` and `Storage` configuration which will be further passed to respective `NetworkController` and `StorageController`.
+It serves as a means to configure network, storage, type of machine and other information needed to create a VM. The `MachineController` reconciler leverages this information to determine where the machine needs to be created and the type of machine that needs to be created along with the required `Network` and `Storage` configuration which will be further passed to respective `NetworkController` and `StorageController`.
 
 ## Example Machine Resource
 
-An example of how to define an Machine resource:
+An example of how to define a Machine resource:
 
 ```yaml
 apiVersion: compute.ironcore.dev/v1alpha1
@@ -19,7 +19,7 @@ spec:
   #    name: default
   image: my-image
   volumes:
-    - name: rootdisk # first disk is root disk
+    - name: rootdisk # first disk is the root disk
       # priority: 0 # optional
       volumeRef:
         name: my-volume
@@ -35,38 +35,38 @@ spec:
 **Key Fields**:
 
 - machineClassRef (`string`): MachineClassRef is a reference to the machine class/flavor of the machine.
-- machinePoolRef (`string`): MachinePoolRef defines machine pool to run the machine in. If empty, a scheduler will figure out an appropriate pool to run the machine in.
+- machinePoolRef (`string`): MachinePoolRef defines the machine pool to run the machine in. If empty, a scheduler will figure out an appropriate pool to run the machine in.
 - image (`string`): Image is the optional URL providing the operating system image of the machine.
 - volumes (`list`): Volumes are list volumes(Storage) attached to this machine.
 - networkInterfaces (`list`): NetworkInterfaces define a list of network interfaces present on the machine
-- ignitionRef (`string`): IgnitionRef is a reference to a secret containing the ignition YAML for the machine to boot up. If key is empty, DefaultIgnitionKey will be used as fallback.
+- ignitionRef (`string`): IgnitionRef is a reference to a secret containing the ignition YAML for the machine to boot up. If a key is empty, DefaultIgnitionKey will be used as a fallback.
 
 
 ## Reconciliation Process
 
-1. **Machine Scheculing**: 
+1. **Machine Scheduling**: 
 The MachineScheduler controller continuously watches for machines without an assigned MachinePool and tries to schedule it on available and matching MachinePool.
   - **Monitor Unassigned Machines**: The scheduler continuously watches for machines without an assigned `machinePoolRef`.
   - **Retrieve Available Machine Pools**: The scheduler fetches the list of available machine pools from the cache.
   - **Make Scheduling Decisions**: The scheduler selects the most suitable machine pool based on resource availability and other policies.
   - **Update Cache**: The scheduler updates the cache with recalculated allocatable `machineClass` quantities.
   - **Assign MachinePoolRef**: The scheduler assigns the selected `machinePoolRef` to the machine object.
 
-2. **IRI Machine creation**: Once the Machine is allocated to particular pool, the `MachineController` processes the `Machine` resource and it extracts the `IgnitionData`, `NetworkInterface` and `Volume` information from the `spec` and prepares IRI machine resource.
+2. **IRI Machine creation**: Once the Machine is allocated to a particular pool, the `MachineController` processes the `Machine` resource and it extracts the `IgnitionData`, `NetworkInterface` and `Volume` information from the `spec` and prepares IRI machine resource.
 
-3. **Machine Brokering**: Once IRIMachine object is prepared create/update machine request is sent to broker via IRI interface(via GRPC call). Actual VM is created when request reaches compute provider. Once the response is recieved from IRI call Machine status is updated with status recieved.
+3. **Machine Brokering**: Once IRIMachine object is prepared create/update the machine request is sent to a broker via the IRI interface(via GRPC call). An actual VM is created when the request reaches the compute provider. Once the response is received from IRI call Machine status is updated with the status recieved.
 
-4. **Network Intreface handling**: MachineControllerNetworkinterface takes care of attach/dettach of Network interfaces defined for machine. Once the attachment is successful status is updated from `Pending` to `Attached`.
+4. **Network Interface handling**: MachineControllerNetworkinterface takes care of attaching/detaching Network interfaces defined for the machine. Once the attachment is successful status is updated from `Pending` to `Attached`.
 
 5. **Volume handling**: MachineControllerVolume takes care of attach/detach of Volumes(Storage) defined for machine. Once the attachment is successful status is updated from `Pending` to `Attached`.
 
-6. **Ephemeral resource handling**: If `NetworkIntreface` or `Volume` is defined as ephemeral(i.e. coupled to the lifetime of the machine object) in the machine spec, MachineEphemeralControllers takes care of creating and destroying respective objects on creation/deletion of machine. 
+6. **Ephemeral resource handling**: If `NetworkIntreface` or `Volume` is defined as ephemeral(i.e. coupled to the lifetime of the machine object) in the machine spec, MachineEphemeralControllers takes care of creating and destroying respective objects on creation/deletion of the machine. 
 
 ## Lifecycle and States
 
-A Machine can be in a following states:
-1. **Pending**:  A Machine is in Pending state when the Machine has been accepted by the system, but not yet completely started. This includes time before being bound to a MachinePool, as well as time spent setting up the Machine on that MachinePool. 
+A Machine can be in the following states:
+1. **Pending**:  A Machine is in a `Pending`  state when the Machine has been accepted by the system, but not yet completely started. This includes time before being bound to a MachinePool, as well as time spent setting up the Machine on that MachinePool. 
 2. **Running**: A Machine in Running state when the machine is running on a MachinePool.
-2. **Shutdown**: A Machine is in Shutdown state.
-3. **Terminating**: A Machine is in Terminating state.
-2. **Terminated**: A Machine is in Terminated state when the machine has been permanently stopped and cannot be started.
+2. **Shutdown**: A Machine is in a Shutdown state.
+3. **Terminating**: A Machine is Terminating.
+2. **Terminated**: A Machine is in the Terminated state when the machine has been permanently stopped and cannot be started.

docs/usage/compute/machineclass.md

@@ -1,10 +1,10 @@
 # MachineClass
 
-A `MachineClass` is a `IronCore` resource used to represent a class/flavor of a Machine. It serves as a means to define an amount of resources a `Machine` object can have as capabilities(For eg, CPU, memory) if associated with particular class. The `MachineClassController` reconciler leverages this information create `MachineClass`.
+A `MachineClass` is an `IronCore` resource used to represent a class/flavor of a Machine. It serves as a means to define the number of resources a `Machine` object can have as capabilities(For eg, CPU, memory) associated with a particular class. The `MachineClassController` reconciler leverages this information to create `MachineClass`.
 
 ## Example Machine Resource
 
-An example of how to define an MachineClass resource:
+An example of how to define a MachineClass resource:
 
 ```yaml
 apiVersion: compute.ironcore.dev/v1alpha1
@@ -18,11 +18,11 @@ capabilities:
 
 **Key Fields**:
 
-- capabilities (`ResourceList`): capabilities is used to define a list of resources a Machine can have along with its capacity.
+- capabilities (`ResourceList`): capabilities are used to define a list of resources a Machine can have along with its capacity.
 
 
 ## Reconciliation Process
 
 - **MachineClass Creation**: The `MachineClassController` uses the `capabilities` field in the MachineClass resource to create a flavor of MachineClass resource.
-- **MachineClass Deletion**: Before deleting any MachineClass its been ensured that it is not in use by any `Machine` and then only deleted.
+- **MachineClass Deletion**: Before deleting any MachineClass it's been ensured that it is not in use by any `Machine` and then only deleted.
 

docs/usage/compute/machinepool.md

@@ -4,7 +4,7 @@ A `MachinePool` is a resource in `IronCore` that represents a pool of compute re
 
 ## Example MachinePool Resource
 
-An example of how to define an MachinePool resource:
+An example of how to define a MachinePool resource:
 
 ```yaml
 apiVersion: compute.ironcore.dev/v1alpha1
@@ -24,8 +24,8 @@ For example `ironcore://shared`
 
 ## Reconciliation Process
 
-- **Machine Type Discovery**: It constantly checks what kinds of machine (MachineClasses) are available in the `Ironcore` Infrastructure
-- **Compatibility Check**: Evaluating whether the MachinePool can manage available machine class based on its capabilities. 
+- **Machine Type Discovery**: It constantly checks what kinds of MachineClasses are available in the `Ironcore` Infrastructure
+- **Compatibility Check**: Evaluating whether the MachinePool can manage available machine classes based on its capabilities. 
 - **Status Update**: Updating the MachinePool's status to indicate the supported `MachineClasses` with available capacity and allocatable.
 - **Event Handling**: Watches for changes in MachineClass resources and ensures the associated MachinePool is reconciled when relevant changes occur.