Knative文档编写规范与格式指南

Knative文档编写规范与格式指南

docs User documentation for Knative components. 项目地址: https://gitcode.com/gh_mirrors/docs1/docs

前言

作为云原生领域的重要项目，Knative的文档质量直接影响用户体验。本文将详细介绍Knative文档的编写规范与格式要求，帮助技术作者编写出专业、一致的文档内容。

标题与章节规范

标题大小写规则

Knative文档采用句子式大小写（Sentence case）：

• 仅首字母大写
• 专有名词和缩写保持大写
• 不使用全大写格式

正确示例：

## 配置Knative事件代理
### 使用HTTPS协议

错误示例：

## 配置Knative事件代理
### 使用HTTPS协议

标题中的代码格式

避免在标题中使用代码格式标记，保持标题简洁清晰。

正确示例：

## 配置类注解

错误示例：

## 配置`class`注解

操作步骤标题规范

对于操作指南类内容，标题应使用祈使语气，明确指示用户操作。

正确示例：

## 安装Knative服务组件
### 配置DNS解析
## 验证安装结果

错误示例：

## Knative服务组件的安装
### DNS的配置
## 如何验证安装

链接使用规范

链接描述文本

链接文本应清晰描述目标内容，避免使用"点击这里"等模糊表述。

正确示例：

参考[Kafka代理配置指南](../kafka-broker/README.md)获取详细说明

错误示例：

详细说明请点击[这里](../kafka-broker/README.md)

链接格式要求

1. 统一使用Markdown链接语法
2. 内部链接必须包含.md扩展名
3. 链接到具体文件而非目录
4. 注意文件名大小写一致性

正确示例：

[自定义域名设置](../serving/using-a-custom-domain.md)

错误示例：

[自定义域名设置](../serving/using-a-custom-domain)

内容格式规范

单位表示方法

1. 数字与单位间使用不间断空格(&nbsp)
2. 百分比(%)直接连接数字

正确示例：

分配4 GB内存
设置CPU限制为2 核
成功率保持在95%

错误示例：

分配4 GB内存
设置CPU限制为2核
成功率保持在95 %

界面元素标注

用户界面元素使用加粗格式，避免引号。

正确示例：

点击**提交**按钮
选择**高级选项**

错误示例：

点击"提交"按钮
选择"高级选项"

术语定义表

术语解释推荐使用表格形式，提高可读性。

推荐格式：

| 术语       | 说明                     |
|------------|--------------------------|
| Revision   | 代码和配置的时间点快照   |
| Route      | 流量路由规则定义         |

技术术语规范

API对象命名

Knative API对象采用大驼峰命名法。

正确示例：

创建新的Broker实例
配置Channel参数

错误示例：

创建新的broker实例
配置channel参数

缩写使用规范

仅在首次出现时用括号注明缩写，避免其他括号用法。

正确示例：

自定义资源定义(CRD)是Kubernetes的扩展机制

错误示例：

检查你的CLI(应该能看到结果)

标点符号规范

遵循国际标准，标点符号放在引号外。

正确示例：

这个状态被称为"就绪"。

错误示例：

这个状态被称为"就绪。"

最佳实践建议

1. 保持语言简洁直接，避免冗长描述
2. 技术术语使用前后一致
3. 复杂概念配图说明
4. 代码示例保持完整可运行
5. 重要步骤提供验证方法

通过遵循这些规范，可以确保Knative文档保持专业性和一致性，为用户提供最佳的技术参考体验。

docs User documentation for Knative components. 项目地址: https://gitcode.com/gh_mirrors/docs1/docs