diff --git a/docs/book/src/reference/good-practices.md b/docs/book/src/reference/good-practices.md index 443bece4fc4..cfb376f8ceb 100644 --- a/docs/book/src/reference/good-practices.md +++ b/docs/book/src/reference/good-practices.md @@ -24,7 +24,23 @@ Avoid a design solution where the same controller reconciles more than one Kind. ## Why You Should Adopt Status Conditions -We recommends you to manage your solutions using Status Conditionals. You can check the scaffold provided via the [deploy-image][deploy-image] as an example for its implementation. +We recommend you manage your solutions using Status Conditionals following the [K8s Api conventions][k8s-aoi-convetions] because: + +- **Standardization**: Conditions provide a standardized way to represent the state of an Operator's custom resources, making it easier for users and tools to understand and interpret the resource's status. +- **Readability**: Conditions can clearly express complex states by using a combination of multiple conditions, making it easier for users to understand the current state and progress of the resource. +- **Extensibility**: As new features or states are added to your Operator, conditions can be easily extended to represent these new states without requiring significant changes to the existing API or structure. +- **Observability**: Status conditions can be monitored and tracked by cluster administrators and external monitoring tools, enabling better visibility into the state of the custom resources managed by the Operator. +- **Compatibility**: By adopting the common pattern of using conditions in Kubernetes APIs, Operator authors ensure their custom resources align with the broader ecosystem, which helps users to have a consistent experience when interacting with multiple Operators and resources in their clusters. + + Additionally, we recommend checking the documentation on [Operator patterns][operator-pattern] from Kubernetes to better understand the purpose of the standard solutions that are built with KubeBuilder.