如何贡献文档?
本文主要针对已有的文档做局部修改。如果是投稿博客文章、添加新的文档或者调整文档目录结构请先联系团队成员。
KCL 文档分为用户指南、开发文档、内部文档、参考手册和博客文章等，他们的区别如下：
- 用户指南：对应使用文档，是让用户以最小的代价快速使用 KCL 工具完整工作，不要涉及太多的内部原理和实现
- 开发文档：内部是怎么实现的，主要针对希望了解 KCL 原理和参与贡献和开发的同学
- 内部文档：针对企业用户的一些内部场景定制的文档
- 参考手册：KCL 语言、工具和 IDE 等全部特性的文档，内容覆盖最广但比较琐碎
- 博客文章：没有特别的限制，可以是针对某些具体的场景、某些技术点或者是整体发展展望等分享文章
在贡献不同类型的文档时，最好能够结合上面的定位对不同的内容做一些适当的裁剪，给读者最佳体验。
1. 基本规范
- 除标题外，内部小标题尽量带编号，便于阅读
- 工具自动输出的文档需要由到源代码的链接，小标题可以不带编号
- 尽量不要贴大段的代码（30行以内），代码最好给出文字解释和对应的参考链接
- 有图有真相，但是不推荐过度复杂的架构图
- 内部链接：采用
/docs/user_docs/getting-started/intro绝对路径形式
标点和空格
- 在中文的文档中优先使用中文的标点
- 中文和英文之间需要增加 1 个空格
- 中文和数字之间需要增加 1 个空格
- 中文使用全角标点，标点前后均不添加空格
- 英文内容使用半角标点，标点后面加 1 个空格
- 链接前后需要保留一个空格，但是段落开头和中文全角标点附近不用添加空格。
图片和资源文件名
- 文件名和目录名只能用数字、英文字母、下划线
_和减号-组成 - 当前文档的图片放在当前目录的 images 目录下
- 矢量图片可以通过 drawio 离线版 绘制（并同时提交源文件），以 200% 分辨率导出 png 格式图片
2. 使用文档内容的基本模式
每个使用文档可以看作是一个相对完整的分享或博客文章（参考手册不再此类）。使用文档遵循以下模式组织内容：
- 概览：本文希望解决什么问题，达到什么效果，可以先放最终效果截图
- 依赖的环境：需要安装什么工具，并给出相关链接
- 引入本文构建资源的关系图或架构图
- 需要用到的 Konfig 模型，给出模型参考页面链接，以及对应的上游原始模型的文档链接
- 具体的操作步骤
- 尽量确保最小化代码，甚至可以刻意隐藏一些干扰代码，同时给出完整代码对应的链接
- 列出每个步骤命令的概要输出信息，并配以文字描述
- 给出测试方式
- 尽量采用社区通用的方式（比如kube、curl命令、或浏览器）测试
- 给出测试结果的截图（和开头呼应）
- 总结和展望
- 简单回顾当前操作的流程，以及一些可以展开的地方（可以给出一些链接）
3. 测试和提交 PR
先克隆文档仓库，本地通过 npm run start 和 npm run build 命令测试查看效果，确保可以正常浏览后提交 PR 即可。