Knative文档编写规范：代码与命令的标准化记录指南

Knative文档编写规范：代码与命令的标准化记录指南

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

前言

在Knative技术文档编写过程中，规范化的代码和命令呈现方式对于用户体验至关重要。本文将深入解析如何专业地记录代码片段、命令行操作和YAML配置，确保文档的一致性和可读性。

代码格式化的应用范围

代码格式化应仅用于特定类型的文本内容：

• 文件名和路径名称
• YAML文件中的字段和值
• 命令行输入内容
• CLI工具名称

代码块语言规范

基本原则

必须明确指定代码块所使用的编程语言。对于非特定语言的代码（如CLI命令），应使用bash标识。

正确示例

package main

import "fmt"

func main() {
    fmt.Println("hello world")
}

错误示例

package main  // 错误：Go代码不应使用bash标识
import "fmt"

func main() {
    fmt.Println("hello world")
}

命令文档编写规范

标准格式

命令文档应采用"通过运行以下命令X Y："的格式，其中：

• X表示操作动作
• Y表示操作对象

正确示范

创建服务时，应使用以下格式：

kn create service <service-name>

其中<service-name>是您要创建的Knative服务名称。

常见错误

1. 缺少"运行"说明：

   创建服务：
   

2. 只有命令没有上下文：

   运行：
   

3. 冗长表述：

   运行以下命令来创建一个服务：
   

YAML文档编写规范

最佳实践

YAML配置应分两步说明：

1. 创建YAML文件
2. 应用YAML配置

创建/更新资源

1. 使用以下模板创建YAML文件：

    ```yaml
    apiVersion: serving.knative.dev/v1
    kind: Service
    metadata:
      name: example-service
    ```

2. 通过运行以下命令应用配置：

    ```bash
    kubectl apply -f service.yaml
    ```

编辑现有配置

kubectl -n knative-serving edit configmap config-autoscaler

错误示范

1. 内联创建方式：

   cat <<EOF | kubectl create -f -
   # 配置内容
   EOF
   

2. 内联应用方式：

   kubectl apply -f - <<EOF
   # 配置内容
   EOF
   

变量引用规范

基本规则

• 使用尖括号包裹变量名：<variable-name>
• 全部小写，单词间用连字符连接
• 在代码块下方解释每个变量

单变量示例

kn create service <service-name>

其中<service-name>是您要创建的Knative服务名称。

多变量示例

kn create service <service-name> --revision-name <revision-name>

其中：

• <service-name>是Knative服务名称
• <revision-name>是修订版本名称

代码片段指示

当展示YAML文件片段时，应使用省略号(...)表示省略的内容。

正确方式

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
...
spec:
  template:
    spec:
      containers:
      - image: gcr.io/knative-samples/helloworld-go
...

错误方式

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
spec:
  template:
    spec:
      containers:
      - image: gcr.io/knative-samples/helloworld-go

CLI输出记录规范

记录命令行输出时，应使用特殊格式禁用复制按钮：

$ kn service list
NAME               URL                                               LATEST               AGE     CONDITIONS   READY   REASON
example-service    http://example-service.default.example.com        example-service-1    1m30s   3 OK / 3     True

命令标志使用规范

优先使用短标志而非长标志：

正确用法

kubectl get pods -n knative-serving

错误用法

kubectl get pods --namespace knative-serving

结语

遵循这些规范将确保Knative文档保持专业、一致且易于理解。无论是代码片段、命令行操作还是配置示例，统一的呈现方式都能显著提升用户的阅读体验和技术文档的质量。

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