7.2 贡献文档

文档是所有软件的对外接口，因此文档的好坏将直接影响用户的体验。作为开源项目，我们可以很容易参与 Kusion 文档的共建。

7.2.1 文档的分类

Kusion 文档分为用户指南、开发文档、内部文档、参考手册和博客文章等，他们的区别如下：

• 用户指南：对应使用文档，是让用户以最小的代价快速使用 Kusion 工具完整工作，不要涉及太多的内部原理和实现
• 开发文档：内部是怎么实现的，主要针对希望了解 Kusion 原理和参与贡献和开发的同学
• 内部文档：针对企业用户的一些内部场景定制的文档
• 参考手册：Kusion 工具、KCL 配置语言、模型库 等全部特性的文档，内容覆盖最广但比较琐碎
• 博客文章：没有特别的限制，可以是针对某些具体的场景、某些技术点或者是整体发展展望等分享文章

在贡献不同类型的文档时，最好能够结合上面的定位对不同的内容做一些适当的裁剪，给读者最佳体验。如果是添加文档或者是投稿博客文章、添加新的文档或者调整文档目录结构请先联系团队成员。

7.2.2 基本规范

• 除标题外，内部小标题尽量带编号，便于阅读
• 工具自动输出的文档需要由到源代码的链接，小标题可以不带编号
• 尽量不要贴大段的代码（30 行以内），代码最好给出文字解释和对应的参考链接
• 有图有真相，但是不推荐过度复杂的架构图

标点和空格

• 在中文的文档中优先使用中文的标点
• 中文和英文之间需要增加 1 个空格
• 中文和数字之间需要增加 1 个空格
• 中文使用全角标点，标点前后均不添加空格
• 英文内容使用半角标点，标点后面加 1 个空格
• 链接前后需要保留一个空格，但是段落开头和中文全角标点附近不用添加空格。

图片和资源文件名

• 文件名和目录名只能用数字、英文字母、下划线 _ 和减号 - 组成
• 当前文档的图片放在当前目录的 images 目录下
• 矢量图片可以通过 drawio 离线版 绘制（并同时提交源文件），以 200% 分辨率导出 png 格式图片
• 矢量图也可以通过 Mermaid 在 Markdown 中直接绘制

7.2.3 使用文档内容的基本模式

每个使用文档可以看作是一个相对完整的分享或博客文章（参考手册不再此类）。使用文档遵循以下模式组织内容：

1. 概览：本文希望解决什么问题，达到什么效果，可以先放最终效果截图
2. 依赖的环境：需要安装什么工具，并给出相关链接
3. 引入本文构建资源的关系图或架构图
   • 需要用到的 Konfig 模型，给出模型参考页面链接，以及对应的上游原始模型的文档链接
4. 具体的操作步骤
   • 尽量确保最小化代码，甚至可以刻意隐藏一些干扰代码，同时给出完整代码对应的链接
   • 列出每个步骤命令的概要输出信息，并配以文字描述
5. 给出测试方式
   • 尽量采用社区通用的方式（比如 kube、curl 命令、或浏览器）测试
   • 给出测试结果的截图（和开头呼应）
6. 总结和展望
   • 简单回顾当前操作的流程，以及一些可以展开的地方（可以给出一些链接）

7.2.4 测试和提交 PR

先克隆文档仓库，本地通过 npm run start 和 npm run build 命令测试查看效果，可以参考 构建文档。确保可以正常浏览后提交 PR 即可。