Merge pull request #155 from Peefy/polish-intro-docs

refactor: polish kcl introduction documents

Author: Peefy

docs/user_docs/getting-started/intro.md

@@ -10,27 +10,32 @@ sidebar_position: 1
 
 ## Why Use KCL?
 
-KCL expects to solve the following problems:
+KCL aims to fill the gap in configuration languages and tools in the lightweight client-side cloud-native dynamic configuration domain through a more modern declarative configuration language and tools. It aims to address the following problems:
+
++ **Dimension explosion**: Most static configurations, such as Kubernetes YAML configurations in the cloud-native domain, require separate configurations for each environment. In the worst case, this can introduce difficult-to-debug errors involving cross-environment links, resulting in poor stability and scalability.
++ **Configuration drift**: There is often no standardized way to manage the dynamic configurations of applications and infrastructure for different environments, leading to configuration drift. Using non-standardized methods, such as scripting and piecing together glue code, can exponentially increase complexity and lead to configuration drift.
++ **Cognitive loading**: Platform technologies such as Kubernetes excel in unifying infrastructure details at the lower level, but lack higher-level application software delivery abstractions. This creates a higher cognitive loading for regular developers and affects the software delivery experience for developers at higher levels.
+
+To address these problems, KCL aims to provide the following capabilities:
 
 + Hide infrastructure and platform details by defining more appropriate **API abstractions** to reduce the burden of developers.
 + **Mutate** and **validate** existing config files or manifests.
-+ Manage large-scale configuration data across teams without side effects through configuration language.
-  + Use **production level high-performance programming language** to **write code** to improve the flexibility of configuration, such as conditional statements, loops, functions, package management and other features to improve the ability of configuration reuse.
-  + Improve the ability of **configuration semantic verification** at the code level, such as optional/required fields, types, ranges, and other configuration checks.
-  + Provide the **ability to write, combine and abstract configuration blocks**, such as structure definition, structure inheritance, constraint definition, etc.
-
-You can use KCL to
++ **Manage large-scale configuration data** across teams without side effects through configuration language.
 
-+ **Generate** low-level static configuration data like JSON, YAML, etc.
-+ Reduce boilerplate in configuration data with the **schema modeling**.
-+ Define transformers and constraints for configuration data and templates and **mutate/validate** them automatically.
-+ Organize, simplify, unify and manage large configurations scalably without side effects.
-+ Used as a platform engineering language to deliver modern app with [KusionStack](https://kusionstack.io/).
+Specifically, KCL can
 
-In addition to the language itself, KCL also provides many additional tools, such as formatting, testing, document, package management, to help users use, understand and check the configuration or policy they write. We can reduce the cost of configuration writing and sharing through IDE extensions such as VS Code, playground and package manage tools. In addition, through KCL Rust, Go, and Python multilingual SDKs, the configuration can be automatically managed and executed.
++ Improve the ability to **semantically validate configurations** at the code level, such as schema definitions, required/optional attribute requirements, types, range constraints, and etc.
++ Provide capabilities for **writing, combining, and abstracting configuration chunks**, such as structure definitions, structure inheritance, constraint definitions, and configuration policy merging.
++ Enhance configuration flexibility by adopting **modern programming language** features, such as conditional statements, loops, functions, and package management, to improve configuration reusability.
++ Provide **comprehensive toolchain support**, including rich IDE extensions and toolchains support to reduce the learning curve and enhance the user experience.
++ Enable easier sharing, propagation, and delivery of configurations between different teams/roles through **package management tools** and **OCI registries**.
++ Offer a **high-performance** compiler to meet the demands of scalable configuration scenarios, such as rendering performance for generating configurations for different environments and topologies based on a baseline configuration and configuration automation modification performance requirements.
++ Improve **automation integration** capabilities through **multi-language SDKs**, **KCL language plugins**, and other means, significantly reducing the learning curve while leveraging the value of configuration and policy writing with KCL.
 
 ![](/img/docs/user_docs/intro/kcl-overview.png)
 
+In addition to the language itself, KCL also provides many additional tools, such as formatting, testing, document, package management, to help users use, understand and check the configuration or policy they write. We can reduce the cost of configuration writing and sharing through IDE extensions such as VS Code, playground and package manage tools. In addition, through KCL Rust, Go, and Python multilingual SDKs, the configuration can be automatically managed and executed.
+
 Besides, KCL is a modern high-level domain language, which is a compiled, static and strongly typed language. It provides developers with the ability to write **configuration (config)**, **modeling abstraction (schema)**, **logic (lambda)**, and **policies (rule)** as the core elements through recording and functional language design.
 
 ![](/img/docs/user_docs/intro/kcl-concepts.png)
@@ -194,6 +199,6 @@ Furthermore, general-purpose languages come in a variety of styles, which can cr
 
 While not originally intended as a data definition language, Rego, the language used for Open Policy Agent (OPA), can also address the issue of adding constraints from multiple sources.
 
-Rego has its roots in logic programming and is based on Datalog, a restricted form of Prolog. In contrast, KCL is based on a static type structure. Typed-feature structures were developed to address the limitations of Prolog in encoding human languages. Using a Datalog variant for a constraint validation task may seem unusual. Datalog excels as a query language, but it can be cumbersome for constraint enforcement, in that values must be queried before applying constraints.
+Rego has its roots in logic programming and is based on Datalog, a restricted form of Prolog. Rego excels as a query language, but it can be cumbersome for constraint enforcement, in that values must be queried before applying constraints. Besides, Rego itself does not have the ability to define a schema. You can introduce JsonSchema definitions in Rego's comments when needed.
 
 KCL's approach to constraint validation is more conducive to finding normalized and simplified representations of constraints, making it well-suited for creating structures generated from OpenAPI.

i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/getting-started/intro.md

@@ -10,29 +10,32 @@ sidebar_position: 1
 
 ## 为什么使用 KCL?
 
-KCL 期望通过更现代化的声明式配置语言在 Kubernetes 资源管理解决如下问题：
+KCL 期望通过更现代化的声明式配置语言和工具，在轻量级客户端云原生动态配置领域填补配置语言及工具的空白并解决如下问题：
 
-+ 通过**代码抽象**等手段屏蔽基础设施和平台的细节，降低研发者负担
-+ **编辑**和**校验**已有的存量配置或模版
-+ 通过配置语言无副作用地管理跨团队的大规模配置数据，提升团队协作效率
-  + 用**生产级高性能编程语言**以**编写代码**的方式提升配置的灵活度，比如条件语句、循环、函数、包管理等特性提升配置重用的能力
-  + 在代码层面提升**配置语义验证**的能力，比如字段可选/必选、类型、范围等配置检查能力
-  + 提供**配置分块编写、组合和抽象的能力**，比如结构定义、结构继承、约束定义等能力
-  + 通过**多语言 SDK**，**KCL 语言插件**等手段提升其**自动化**集成能力
++ **维度爆炸**: 大多数静态配置如云原生领域的 Kubernetes YAML 配置需要为每个环境单独进行配置；在最糟糕的情况下，它可能引入涉及环境交叉链接的难以调试的错误，稳定性和扩展性都较差。
++ **配置漂移**: 对于不同环境的静态管理应用程序和基础设施配置的方式，往往没有标准的方式去管理这些动态的不同环境的配置，采用非标准化的方法比如脚本和胶水代码的拼盘，会导致复杂度呈指数增长，并导致配置漂移。
++ **认知负担**: Kubernetes 等作为构建平台的平台技术手段在底层统一基础架构细节方面出色，但是缺乏更上层的应用软件交付抽象，对于普通开发者认知负担较高，影响了更上层应用开发者的软件交付体验。
 
-您可以将 KCL 用于
+针对如上问题，KCL 期望提供如下能力:
 
-+ 生成静态配置数据如 JSON, YAML 等
-+ 使用 schema 对配置数据进行建模并减少配置数据中的样板文件
-+ 为配置数据定义带有规则约束的 schema 并对数据进行自动验证
-+ 无副作用地组织、简化、统一和管理庞大的配置
-+ 通过分块编写配置数据可扩展地管理庞大的配置
-+ 与 [KusionStack](https://kusionstack.io) 一起，用作平台工程语言来交付现代应用程序
++ 通过**代码抽象**等手段屏蔽基础设施和平台的细节和复杂性，降低研发者**认知负担**
++ **编辑**和**校验**已有的存量配置或模版，直接解决云原生小配置场景问题如 Helm Chart 配置硬编码问题，但远不止如此
++ 通过配置语言无副作用地**管理跨团队的大规模配置数据**，提升团队协作效率
 
-除了语言自身，KCL 还提供了许多额外的工具如格式化，测试、文档、包管理等工具帮助您使用、理解和检查编写的配置或策略；通过 VS Code 等 IDE 插件和 Playground 降低配置编写、分享的成本；通过 Rust, Go, 和 Python 多语言 SDK 自动化地管理和执行配置。
+具体来说，KCL 可以
+
++ 在代码层面提升**配置语义验证**的能力，比如 Schema 定义、字段可选/必选、类型、范围等配置检查校验能力
++ 提供**配置分块编写、组合和抽象**的能力，比如结构定义、结构继承、约束定义和配置策略合并等能力
++ 用**现代编程语言**的方式以**编写代码**的方式提升配置的灵活度，比如条件语句、循环、函数、包管理等特性提升配置重用的能力
++ 提供**完备的工具链支持**，丰富的 IDE 插件、语言和生态工具链支持用以降低上手门槛，提升使用体验
++ 通过**包管理工具** 和 **OCI 注册表**使得配置以更简单的方式在不同团队/角色之间分享，传播和交付
++ 提供**高性能**的编译器满足规模化配置场景诉求，比如满足由一份基线配置根据部署上下文生成不同环境不同拓扑的配置的渲染性能以及配置自动化修改性能诉求
++ 通过**多语言 SDK，KCL 语言插件**等手段提升其**自动化集成**能力，在发挥配置及策略编写价值的同时显著降低 KCL 的学习成本
 
 ![](/img/docs/user_docs/intro/kcl-overview.png)
 
+除了语言自身，KCL 还提供了许多额外的工具如格式化，测试、文档、包管理等工具帮助您使用、理解和检查编写的配置或策略；通过 VS Code 等 IDE 插件和 Playground 降低配置编写、分享的成本；通过 Rust, Go, 和 Python 多语言 SDK 自动化地管理和执行配置。
+
 此外，KCL 是一种现代高级领域编程语言，并且它是一种编译静态的强类型语言。KCL 为开发人员提供了通过记录和函数语言设计将**配置（config）**、**建模抽象（schema）**、**逻辑（lambda）**和**策略（rule）**作为核心能力。
 
 ![](/img/docs/user_docs/intro/kcl-concepts.png)
@@ -148,7 +151,7 @@ Jsonnet 和 GCL 非常擅长减少样板。它们都可以使用代码生成配
 
 HCL 是一种 Go 实现的结构化配置语言。HCL 的原生语法受到 libucl 和 nginx 配置的启发。它用于创建一种对人类和机器友好的结构化配置语言，作为 [Terraform 语言](https://www.terraform.io/language)主要用于 DevOps工具、服务器配置和资源配置等。
 
-HCL 的用户界面不能通过 Terraform 提供者 Schema 定义直接感知。此外，在编写复杂对象和必需/可选字段定义时，用户界面很麻烦。动态参数受变量的条件字段约束。资源本身的约束需要由提供程序模式定义，或者与 Sentinel/Rego 和其他策略语言相结合。语言本身的完整性不能自我封闭，其实现方法也不统一。
+HCL 的用户界面不能通过 Terraform Provider Schema 定义直接感知。此外，在编写复杂对象和必需/可选字段定义时，用户界面很麻烦。动态参数受变量的条件字段约束。资源本身的约束需要由提供程序模式定义，或者与 Sentinel/Rego 和其他策略语言相结合。语言本身的完整性不能自我封闭，其实现方法也不统一。
 
 ### vs. CUE
 
@@ -164,7 +167,7 @@ Dhall 是一种可编程配置语言，它组合了 JSON、函数、类型和 im
 
 Nickel 是一种简单的配置语言。它的目的是自动生成静态配置文件，本质上是带有函数和类型的 JSON。
 
-KCL 和 Nickel 都有类似的渐进式类型系统（静态+动态）、合并策略、函数和约束定义。不同之处在于 KCL 是一种类似 Python 的语言，而 Nickel 是一种类似 JSON 的语言。此外，KCL 提供了 schema 关键字来区分配置定义和配置数据，以避免混合使用。
+KCL 和 Nickel 都有类似的渐进式类型系统（静态+动态）、合并策略、函数和约束定义。不同之处在于 KCL 是一种类似 Python 的语言，而 Nickel 是一种类似 JSON 的函数式语言。此外，KCL 提供了 schema 关键字来区分配置定义和配置数据，以避免混合使用。
 
 ### vs. Starlark
 
@@ -174,26 +177,26 @@ KCL 一定程度上也可以看作 Python 的变种，但是它极大地增强
 
 ### vs. Kustomize
 
-Kustomize 的核心功能是其文件级覆盖功能。但是它存在多个覆盖链的问题，因为找到特定属性值的语句不能保证它是最终值，因为其他地方出现的另一个特定值可以覆盖它。对于复杂的场景，Kustomsize 文件的继承链的检索通常不如 KCL 代码的继承链检索方便，需要仔细考虑指定的配置文件覆盖顺序。此外，Kustomize 无法解决 YAML 配置编写、约束验证、模型抽象和开发等问题，更适合于简单的配置场景。
+Kustomize 的核心功能是其文件级覆盖功能。但是它存在多个覆盖链的问题，因为找到特定属性值的语句不能保证它是最终值，因为其他地方出现的另一个特定值可以覆盖它。对于复杂的场景，Kustomize 文件的继承链的检索通常不如 KCL 代码的继承链检索方便，需要仔细考虑指定的配置文件覆盖顺序。此外，Kustomize 无法解决 YAML 配置编写、约束验证、模型抽象和开发等问题，更适合于简单的配置场景。
 
 在 KCL 中，配置合并操作可以对代码中的每个配置属性进行细粒度处理，合并策略可以灵活设置，而不限于整体资源，配置之间的依赖关系可以通过KCL的import语句进行静态分析。
 
 ### vs. Helm
 
 Helm 的概念源于操作系统的包管理机制。它是一个基于模板化 YAML 文件的包管理工具，支持包中资源的执行和管理。
 
-KCL 自然提供了 Helm 功能的超集，因此您可以直接使用 KCL 作为替代。对于采用 Helm 的用户，KCL 中的堆栈编译结果可以打包并以 Helm 格式使用，通过 kpm 包管理工具进行分发复用。此外，我们还可以直接使用 Helm-KCL 插件直接对已有的 Helm Charts 进行无侵入的可编程扩展。
+KCL 自然提供了 Helm 功能的超集以及 Helm KCL 插件，因此您可以直接使用 KCL 作为替代。对于采用 Helm 的用户，KCL 中的堆栈编译结果可以打包并以 Helm 格式使用，通过 kpm 包管理工具进行分发复用。此外，我们还可以直接使用 Helm-KCL 插件直接对已有的 Helm Charts 进行无侵入的可编程扩展。
 
 ### vs. CDK
 
-用CDK的高级语言编写可以很好地集成到应用程序项目中，这实际上是客户端运行时的一部分。对于KCL，由KCL编写的外部配置和策略与客户端运行时分离。
+用 CDK 的高级语言编写可以很好地集成到应用程序项目中，这实际上是客户端运行时的一部分。对于 KCL，由 KCL 编写的外部配置和策略与客户端运行时分离。
 
-通用语言通常远远超出了需要解决的问题，例如安全问腿、能力边界问题（启动本地线程、访问IO、网络、代码无限循环和其他安全风险）。例如，在音乐领域，有专门的音符来表达音乐，这便于学习和交流，它不能用一般语言表达清楚。
+通用语言通常远远超出了需要解决的问题，例如安全问腿、能力边界问题（启动本地线程、访问 IO、网络、代码无限循环和其他安全风险）。例如，在音乐领域，有专门的音符来表达音乐，这便于学习和交流，它不能用一般语言表达清楚。
 
 此外，由于通用语言风格多样，需要统一维护、管理和自动化。通用语言通常用于编写客户端运行时，它是服务器运行时的延续，不适合编写独立于运行时的配置，被编译成二进制文件，并最终从进程开始运行。此外，GPL 稳定性和可扩展性不易控制。然而，KCL 配置语言通常用于编写数据，将数据与简单逻辑相结合，它描述了预期的最终结果，然后由编译器或引擎使用，既具备丰富的编程抽象能力，又具备方便的数据处理方式。
 
 ### vs. OPA/Rego
 
-Rego 起源于逻辑编程，它基于 Datalog，是一种受限制的 Prolog 形式，而 KCL 基于静态类型结构，具备部分 OOP 特性。Rego 类型化特征结构的设计是为了解决 Prolog 在人类语言编码应用中的缺点，将 Datalog 变量用于编程本质上是约束验证任务，Datalog 是一种优秀的查询语言。但对于约束强制执行，它有点麻烦，因为实际上首先需要查询要应用约束的值才能进行校验。
+Rego 起源于逻辑编程，它基于 Datalog，是一种受限制的 Prolog 形式，而 KCL 基于静态类型结构，具备部分 OOP 特性。Rego 是一种优秀的查询语言。但对于约束强制执行，它有点麻烦，因为实际上首先需要查询要应用约束的值才能进行校验。此外，Rego 本身不具备定义 Schema 的能力，您可以在需要时在 Rego 的注释中引入 JsonSchema 定义。
 
 此外，KCL 的方法更易于找到规范化、简化、面向人类易读，面向运行时性能优良的约束和校验表示，具备静态类型，并且它更适合于从 OpenAPI 生成或者创建 OpenAPI。