Update concept doc (#1556)

README.md

@@ -18,15 +18,17 @@
 
 Traditional *Platform-as-a-Service (PaaS)* systems enable easy application deployments, but this happiness disappears when your application outgrows the capabilities of your platform. This is inevitable regardless of your PaaS is built on Kubernetes or not - the root cause is its inflexibility.
 
-KubeVela is a modern application platform that adapts to your needs, not the other way around.
+KubeVela is a modern application platform that is fully self-service, and adapts to your needs when you grow.
+
+Leveraging Kubernetes as control plane, KubeVela itself is runtime agnostic. It allows you to deploy (and manage) containerized workloads, cloud functions, databases, or even EC2 instances with a consistent workflow.
 
 ## Features
 
 **Developer Centric** - KubeVela introduces higher level API to capture a full deployment of microservices, and builds features around the application needs only. Progressive rollout and multi-cluster deployment are provided out-of-box. No infrastructure level concerns, simply deploy.
 
-**Platform-as-Code** - KubeVela models platform features (such as workloads, operational behaviors, and cloud services) as reusable [CUE](https://github.com/cuelang/cue) and/or [Helm](https://helm.sh/) components, per needs of your application. And when your needs grow, these capabilities can expand naturally in a programmable approach. No restriction, fully extensible.
+**Self-service** - KubeVela models platform features (such as workloads, operational behaviors, and cloud services) as reusable [CUE](https://github.com/cuelang/cue) and/or [Helm](https://helm.sh/) components, and expose them to end users as self-service building blocks. When your needs grow, these capabilities can extend naturally in a programmable approach. No restriction, fully flexible.
 
-**Simple yet Reliable** - KubeVela enforces those programmable components with [Kubernetes Control Loop](https://kubernetes.io/docs/concepts/architecture/controller/) so they will never leave configuration drift in your clusters. Also, this makes KubeVela work with any CI/CD or GitOps tools via declarative API without any integration burden.
+**Simple yet Reliable** - KubeVela is built with Kubernetes as control plane so unlike traditional X-as-Code solutions, it never leaves configuration drift in your clusters. Also, this makes KubeVela work with any CI/CD or GitOps tools via declarative API without any integration burden.
 
 ## Getting Started
 

docs/en/README.md

@@ -4,7 +4,7 @@
 
 # KubeVela
 
-KubeVela is a modern application platform that adapts to your needs, not the other way around.
+KubeVela is a modern application platform that is fully self-service, and adapts to your needs when you grow.
 
 ## Community
 

docs/en/concepts.md

@@ -8,26 +8,27 @@ In this documentation, we will explain the core idea of KubeVela and clarify som
 
 First of all, KubeVela introduces a workflow with separate of concerns as below:
 - **Platform Team**
-  - Model deployment environments and platform capabilities as reusable templates, then register them into Kubernetes.
+  - Model and manage platform capabilities as components or traits, together with deployment environment configurations.
 - **End Users**
-  - Choose a deployment environment, assemble the app with available templates per needs, and then deploy the app to target environment.
+  - Choose a deployment environment, assemble the app with available components and traits per needs, and then deploy the app to target environment.
 
 Below is how this workflow looks like:
 
 ![alt](resources/how-it-works.png)
 
-This design make it possible for platform team to enforce best practices by *coding* platform capabilities into templates, and leverage them to expose a *PaaS-like* experience (*i.e. app-centric abstractions, self-service workflow etc*) to end users.
+This design make it possible for platform team to enforce best practices by *coding* platform capabilities into reusable building blocks, and leverage them to expose a *PaaS-like* experience (*i.e. app-centric abstractions, self-service workflow etc*) to end users.
 
-Also, as programmable components, these templates can be updated or extended easily per your needs at any time.
+Also, as programmable components, all capabilities in KubeVela can be updated or extended easily per your needs at any time.
 
 ![alt](resources/what-is-kubevela.png)
 
 In the model layer, KubeVela leverages [Open Application Model (OAM)](https://oam.dev) to make above design happen.
 
 ## `Application`
+
 The *Application* is the core API of KubeVela. It allows developers to work with a single artifact to capture the complete application deployment with simplified primitives.
 
-In application delivery platform, having an "application" concept is important to simplify administrative tasks and can serve as an anchor to avoid configuration drifts during operation. Also, it provides a much simpler path for on-boarding Kubernetes capabilities to application delivery process without relying on low level details. For example, a developer will be able to model a "web service" without defining a detailed Kubernetes Deployment + Service combo each time, or claim the auto-scaling requirements without referring to the underlying KEDA ScaleObject.
+In application delivery platform, having an "application" concept is important to simplify administrative tasks and can serve as an anchor to avoid configuration drifts during operation. Also, it provides a much simpler path for on-boarding Kubernetes capabilities to end users without relying on low level details. For example, a developer will be able to model a "web service" without defining a detailed Kubernetes Deployment + Service combo each time, or claim the auto-scaling requirements without referring to the underlying KEDA ScaleObject.
 
 ### Example
 
@@ -62,17 +63,19 @@ spec:
             image: "fluentd"
 ```
 
-The `Application` resource in KubeVela is a LEGO-style object and does not even have fixed schema. Instead, it is composed by building blocks (app components and traits etc.) that allow you to on-board platform capabilities to this application definition via your own abstractions.
+The `Application` resource in KubeVela is a LEGO-style entity and does not even have fixed schema. Instead, it is composed by several building blocks (app components and traits etc.) that gives you full flexibility to model platform capabilities around the application's needs.
 
-The building blocks to model platform capabilities named `ComponentDefinition` and `TraitDefinition`.
+These building blocks named `ComponentDefinition` and `TraitDefinition`.
 
 ### `ComponentDefinition`
 
-`ComponentDefinition` is a pre-defined *template* for the deployable workload. It contains template, parametering and workload characteristic information as a declarative API resource. 
+`ComponentDefinition` is an object that models a deployable entity in your platform, for example, a *Long Running Web Service*, a *Helm chart* or a *Alibaba Cloud RDS*. In detail, a component definition contains workload type description, template, and a parameter list based on this template.
 
-Hence, the `Application` abstraction essentially declares how the user want to **instantiate** given component definitions in target cluster. Specifically, the `.type` field references the name of installed `ComponentDefinition` and `.properties` are the user set values to instantiate it. 
+Hence, component definition is designed to be shareable and reusable. For example, by referencing the same *Alibaba Cloud RDS* component definition and setting different parameter values, users could easily provision Alibaba Cloud RDS instances of different sizes in different zones.
 
-Some typical component definitions are *Long Running Web Service*, *One-time Off Task* or *Redis Database*. All component definitions expected to be pre-installed in the platform, or provided by component providers such as 3rd-party software vendors.
+The `Application` abstraction is where users declare how they want to **instantiate and deploy** certain component definitions in target environments. Specifically, the `.type` field references the name of a `ComponentDefinition` and `.properties` are user provided parameter values to instantiate it. 
+
+All component definitions expected to be provided by component providers such as 3rd-party software vendors, or pre-installed in the system by platform team.
 
 ### `TraitDefinition`
 
@@ -80,31 +83,31 @@ Optionally, each component has a `.traits` section that augments the component i
 
 Traits are operational features provided by the platform. To attach a trait to component instance, the user will declare `.type` field to reference the specific `TraitDefinition`, and `.properties` field to set property values of the given trait. Similarly, `TraitDefiniton` also allows you to define *template* for operational features.
 
-We also reference component definitions and trait definitions as *"capability definitions"* in KubeVela. 
-
-## Environment
-Before releasing an application to production, it's important to test the code in testing/staging workspaces. In KubeVela, we describe these workspaces as "deployment environments" or "environments" for short. Each environment has its own configuration (e.g., domain, Kubernetes cluster and namespace, configuration data, access control policy, etc.) to allow user to create different deployment environments such as "test" and "production".
-
-Currently, a KubeVela `environment` only maps to a Kubernetes namespace, while the cluster level environment is work in progress.
+We also reference component definitions and trait definitions as *"capabilities"* in KubeVela. 
 
 ### Summary
 
-The main concepts of KubeVela could be shown as below:
+These main concepts of KubeVela could be shown as below:
 
 ![alt](resources/concepts.png)
 
 Essentially:
-- Components - deployable/provisionable entities that composed your application deployment
+- Components - deployable/provisionable entities that composed your application
   - e.g. a Kubernetes workload, a MySQL database, or a AWS S3 bucket
 - Traits - attachable operational features per your needs
   - e.g. autoscaling rules, rollout strategies, ingress rules, sidecars, security policies etc
 - Application - full description of your application deployment assembled with components and traits
 - Environment - the target environments to deploy this application
 
+## Environment
+Before releasing an application to production, it's important to test the code in testing/staging workspaces. In KubeVela, we describe these workspaces as "deployment environments" or "environments" for short. Each environment has its own configuration (e.g., domain, Kubernetes cluster and namespace, configuration data, access control policy, etc.) to allow user to create different deployment environments such as "test" and "production".
+
+Currently, a KubeVela `environment` only maps to a Kubernetes namespace, while the cluster level environment is work in progress.
+
 ## Architecture
 
 The overall architecture of KubeVela is shown as below:
 
 ![alt](resources/arch.png)
 
-Specifically, the application controller is responsible for application abstraction and encapsulation (i.e. the controller for `Application` and `Definition`). The rollout controller will handle progressive rollout strategy with the whole application as a unit. The multi-cluster deployment engine is responsible for deploying the application across multiple clusters and environments with traffic shifting and rollout features supported. 
+Specifically, the application controller is responsible for application abstraction and deployment. The rollout controller will handle progressive rollout strategy with the whole application as a unit. The multi-cluster deployment engine is responsible for deploying the application across multiple clusters and environments with traffic shifting features supported.