update machine controller docs

Signed-off-by: rajaSahil <sahilraja242@gmail.com>

Author: rajaSahil

content/machine-controller/_index.en.md

@@ -3,4 +3,6 @@ title = "machine-controller Docs"
 sitemapexclude = true
 +++
 
-Manage machines at cloud providers using a declarative Kubernetes API, compatible with the Kubernetes cluster-autoscaler.
+The Kubermatic machine-controller is a Kubernetes-native tool responsible for managing the lifecycle of worker nodes across various cloud providers using declarative Kubernetes APIs.
+
+For detailed documentation, please visit the [machine-controller documentation]({{< ref "./main/" >}}).

content/machine-controller/main/_index.en.md

@@ -1,60 +1,103 @@
 +++
-title = "machine-controller"
+title = "Kubermatic machine-controller"
 date = 2024-05-31T07:00:00+02:00
+weight = 7
+description = "Learn how to use Kubermatic machine-controller to manage worker nodes across multiple cloud providers in a declarative way using Kubernetes native APIs."
 +++
 
-# machine-controller
+## What is machine-controller?
+
+The Kubermatic machine-controller is a Kubernetes-native tool responsible for managing the lifecycle of worker nodes across various cloud providers. It uses the [Cluster API][1] to define machines as Kubernetes resources, enabling declarative management of worker nodes in Kubernetes clusters.
+
+The machine-controller works in conjunction with the [Operating System Manager][2] to handle the provisioning and configuration of worker nodes across multi-cloud and on-premise environments.
+
+[1]: https://cluster-api.sigs.k8s.io/
+[2]: https://docs.kubermatic.com/operatingsystemmanager
+
+## Motivation and Background
+
+Kubernetes provides powerful abstractions for managing containerized workloads, but managing the underlying infrastructure (worker nodes) can be challenging, especially in multi-cloud environments. The machine-controller solves this problem by:
+
+- **Declarative Node Management**: Define machines as Kubernetes custom resources, allowing you to manage infrastructure using familiar Kubernetes tools and patterns.
+- **Multi-Cloud Support**: Provision and manage worker nodes across different cloud providers (AWS, Azure, GCP, OpenStack, etc.) using a consistent API.
+- **Integration with Cluster API**: Leverages the industry-standard Cluster API for machine lifecycle management.
+- **Automated Operations**: Handle node provisioning, upgrades, and decommissioning automatically based on declared state.
 
 ## Features
 
 ### What Works
 
-- Creation of worker nodes on…
+- **Creation of worker nodes** on the following cloud providers:
   - Alibaba Cloud
   - AWS
   - Azure
   - DigitalOcean
   - Google Cloud Platform
   - Hetzner Cloud
   - KubeVirt
+  - Linode
   - Nutanix
+  - OpenNebula
   - OpenStack
   - VMware Cloud Director
   - VMware vSphere
-- Using any of these supported distributions ([not all distributions work on all providers](/docs/operating-system.md):
+  - Vultr
+
+- **Operating System Support**: Multiple Linux distributions are supported:
   - Amazon Linux 2
   - Flatcar Linux
   - RedHat Enterprise Linux (RHEL)
   - Rocky Linux
   - Ubuntu
 
-### What Doesn't Work
-
-- Creation of control plane nodes (not planned at the moment, consider using 3rd party tools like
-  [KKP](https://github.com/kubermatic/kubermatic) or [KubeOne](https://github.com/kubermatic/kubeone))
+{{% notice note %}}
+Not all operating systems work on all cloud providers. Please refer to the [Operating Systems]({{< ref "./references/operating-systems/" >}}) documentation for compatibility details.
+{{% /notice %}}
 
-## Supported Kubernetes Versions
+### Supported Kubernetes Versions
 
-machine-controller tries to follow the Kubernetes version
-[support policy](https://kubernetes.io/docs/setup/release/version-skew-policy/) as close as possible.
+machine-controller follows the Kubernetes [version support policy][3] as closely as possible.
 
-Currently supported Kubernetes versions are:
+Currently supported Kubernetes versions:
 
 - 1.34
 - 1.33
 - 1.32
 - 1.31
 
-## Community Providers
+[3]: https://kubernetes.io/docs/setup/release/version-skew-policy/
 
-Some cloud providers implemented in machine-controller have been graciously contributed by community
-members. Those cloud providers are not part of the automated end-to-end tests run by the
-machine-controller developers and thus, their status cannot be guaranteed. The machine-controller
-developers assume that they are functional, but can only offer limited support for new features or
-bugfixes in those providers.
+### Community Providers
 
-The current list of community providers is:
+Some cloud providers implemented in machine-controller have been graciously contributed by community members. These providers are not part of the automated end-to-end tests and their status cannot be fully guaranteed. The machine-controller developers assume they are functional but can only offer limited support for new features or bugfixes.
+
+**Community-supported providers:**
 
 - Linode
 - Vultr
 - OpenNebula
+
+### What Doesn't Work
+
+- **Control plane node creation**: This is not planned at the moment. For full cluster lifecycle management including control plane, consider using [Kubermatic Kubernetes Platform (KKP)][4] or [KubeOne][5].
+
+[4]: https://github.com/kubermatic/kubermatic
+[5]: https://github.com/kubermatic/kubeone
+
+## Table of Content
+
+{{% children depth=5 %}}
+{{% /children %}}
+
+## Further Information
+
+- [machine-controller - GitHub Repository](https://github.com/kubermatic/machine-controller)
+- [Operating System Manager](https://docs.kubermatic.com/operatingsystemmanager)
+- [Cluster API Documentation](https://cluster-api.sigs.k8s.io/)
+
+Visit [kubermatic.com](https://www.kubermatic.com/) for further information.
+
+{{% notice tip %}}
+For latest updates follow us on Twitter [@Kubermatic](https://twitter.com/Kubermatic)
+{{% /notice %}}
+