Address comments

Author: fabriziopandini

docs/book/src/reference/glossary.md

@@ -268,7 +268,7 @@ not limited to be expanded in the future.
 
 Any change to a Machine spec, that is performed without deleting the machines and creating a new one.
 
-Note: changing [in-place mutable fields](#in-place-mutable-fields) is not considered and in-place upgrade.
+Note: changing [in-place mutable fields](#in-place-mutable-fields) is not considered an in-place upgrade.
 
 ### Instance
 
@@ -469,14 +469,14 @@ See [Topology Mutation](../tasks/experimental-features/runtime-sdk/implement-top
 # U
 ---
 
-### Update Lifecycle Hooks
-Is a set of Cluster API [Runtime Hooks](#runtime-hook) called when performing the "can update in-place" decision or
-when performing an [in-place update](#in-place-update).
-
 ### Update Extension
 
 A [runtime extension provider](#runtime-extension-provider) that implements [Update Lifecycle Hooks](#update-lifecycle-hooks).
 
+### Update Lifecycle Hooks
+Is a set of Cluster API [Runtime Hooks](#runtime-hook) called when performing the "can update in-place" decision or
+when performing an [in-place update](#in-place-update).
+
 # W
 ---
 

docs/proposals/20240807-in-place-updates-implementation-notes.md

@@ -7,8 +7,8 @@ into the proposal or into the user-facing documentation for this feature.
 
 ## Notes about in-place update implementation for machine deployments
 
-- In place is always considered as potentially disruptive
-  - in place must respect maxUnavailable
+- In-place update is always considered as potentially disruptive
+  - in-place update must respect maxUnavailable
     - if maxUnavailable is zero, a new machine must be created first, then as soon as there is “buffer” for in-place, in-place update can proceed
   - when in-place is possible, the system should try to in-place update as many machines as possible.
     - maxSurge is not fully used (it is used only for scale up by one if maxUnavailable =0)

docs/proposals/20240807-in-place-updates.md

@@ -100,7 +100,7 @@ This approach, inspired by the principle of immutable infrastructure (the very s
 
 Over time several improvement were made to Cluster API immutable rollouts:
 * Support for delete first strategy, thus making it easier to do immutable rollouts on bare metal / environments with constrained resources.
-* Support for [In place propagation of changes affecting Kubernetes objects only](https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20221003-In-place-propagation-of-Kubernetes-objects-only-changes.md), thus avoiding unnecessary rollouts
+* Support for [In-place propagation of changes affecting Kubernetes objects only](https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20221003-In-place-propagation-of-Kubernetes-objects-only-changes.md), thus avoiding unnecessary rollouts
 * Support for [Taint nodes with PreferNoSchedule during rollouts](https://github.com/kubernetes-sigs/cluster-api/pull/10223), thus reducing Pod churn by optimizing how Pods are rescheduled during rollouts.
 
 Even if the project continues to improve immutable rollouts, most probably there are and there will always be some remaining use cases where it is complex for users to perform immutable rollouts, or where users perceive immutable rollouts to be too disruptive to how they are used to manage machines in their organization:
@@ -321,7 +321,7 @@ end
 
 Please note that:
 - When in-place is possible, the system should try to in-place update as many machines as possible.
-  In practice, this means that maxSurge might be not fully used (it is used only for scale up by one if maxUnavailable =0)
+  In practice, this means that maxSurge might be not fully used (it is used only for scale up by one if maxUnavailable=0)
 - No in-place updates are performed when using rollout strategy on delete.
 
 Please refer to [implementation note](./20240807-in-place-updates-implementation-notes.md) for more details about how the move operation is performed.
@@ -333,8 +333,12 @@ In order to do so:
 - The "can update in-place" decision is performed at MachineSet level by calling the `CanUpdateMachine` hook.
 - Before starting an in-place update, the Machine/InfraMachine/BootstrapConfig are updated
   to the new spec.
-- Machines updating in-place are considered not available, because in-place updates are always considered as potentially disruptive.
-    - If maxSurge is zero, a new machine must be created first, then as soon as there is “buffer” for in-place, in-place update can proceed (to better understand this, you might want to consider that maxSurge in KCP is a way to express if the control plane rollout should scale-in or scale out).
+- If maxSurge is one, a new machine must be created first, then as soon as there is “buffer” for in-place, in-place update can proceed.
+- If maxSurge is zero, in-place update can proceed immediately.
+- Note: to better understand above points, you might want to consider that maxSurge in KCP is a way to express if the 
+  control plane rollout should be performed "scaling-out" or "scaling-in"
+- Note: KCP has its own definition of availability, that is preserved during a rollout no matter of it is performed using
+  in-place updates or regular rollouts.
 
 Notably, while KCP will always try to perform in-place whenever possible, KCP might decide to not perform in-place
 changes when it determines that this might impact the control-plane health.
@@ -366,7 +370,7 @@ Please refer to [implementation note](./20240807-in-place-updates-implementation
 
 ### Machine updates
 
-Once a Machine is marked as `Updating` in place and the Machine's spec has been updated with the desired changes, the Machine controller takes over. This controller is responsible for calling the updaters and tracking the progress of those updaters and exposing this progress in the Machine conditions.
+Once a Machine is marked as `Updating` in-place and the Machine's spec has been updated with the desired changes, the Machine controller takes over. This controller is responsible for calling the updaters and tracking the progress of those updaters and exposing this progress in the Machine conditions.
 
 The Machine controller currently calls only one updater (we are explicitly not trying to design a solution for ordering of execution at this stage. However, determining a specific ordering mechanism or dependency management between update extensions will need to be addressed in future iterations of this proposal).
 
@@ -500,7 +504,7 @@ Given that there are still changes not covered, KCP continue with the next updat
 }
 ```
 
-The difference between current and desired will still be the change applied by the user;
+The difference between current and desired will still be the change applied by the user.
 If instead the `vsphere-vm-memory-update` would have declared its ability to perform some changes via a patch,
 those changes would be applied to change "current" state the second extension should consider.