Canonical/cloud-init 项目文档编写规范指南

Canonical/cloud-init 项目文档编写规范指南

cloud-init Official upstream for the cloud-init: cloud instance initialization 项目地址: https://gitcode.com/gh_mirrors/cl/cloud-init

前言

在开源项目的协作开发中，统一的文档风格对于维护项目知识库的整洁性和可读性至关重要。本文详细解读了 Canonical 旗下 cloud-init 项目的文档编写规范，帮助贡献者快速掌握项目文档的标准化写作方法。

语言规范

基础语言要求

• 采用美式英语(US English)作为主要书写语言
• 在保持专业性的前提下，允许适当灵活处理
• 提倡简洁明了的表达方式

内容组织建议

1. 避免内容重复：当官方文档已有详细说明时，建议直接引用而非重复描述
2. 考虑读者水平：技术文档应照顾不同层次的读者：
   • 对复杂概念应提供背景说明
   • 可添加"延伸阅读"章节引导深入学习
3. 上下文关联：适当添加相关技术背景链接，帮助读者理解

文档结构规范

标题层级系统

cloud-init 文档采用与 Python 风格指南相似的标题层级结构：

##### 顶级标题（仅用于主索引页）
***** 页面标题（每个页面顶部使用一次）
===== 章节标题
----- 小节标题
^^^^^ 子小节标题
""""" 段落标题

重要规则：

• 下划线长度必须≥标题文本长度
• 禁止跳级使用标题（如章节后直接跟子小节）
• 保持层级结构完整性和一致性

格式细节要求

行长度控制

• 严格限制每行79个字符以内
• 避免行末空白字符（会导致构建检查失败）

锚点标签使用

1. 页面级锚点示例：

   .. _faq:
   
   FAQ
   ***
   

2. 章节内部锚点命名规范：
   • 采用[页面标签]-[章节名]格式
   • 例如：_docs-Anchor: 或 _docs-Label:

链接管理规范

• 集中放置：所有链接建议统一放在文档末尾
• 可访问性优化：
  • 避免使用"点击这里"等模糊表述
  • 推荐使用描述性链接文本，如"查看我们的文档风格指南"

内容呈现技巧

多媒体使用建议

1. 截图使用：尽量避免，优先采用代码块展示文本输出
2. 图表制作：推荐使用 Mermaid 等专业图表工具

代码块规范

• 利用 sphinx-copybutton 扩展功能：
  • 自动添加复制按钮
  • 自动去除命令提示符($)
• 最佳实践：
  • 命令与输出分开显示
  • 保持代码块上下文完整

文件命名约定

• 使用反引号标注文件名，如config.yaml
• 保持命名简洁且具有描述性

排版与术语

空白控制

• 章节间保留一个空行
• 段落内保持紧凑

术语统一规范

1. 首字母缩略词：

   • 全部大写（JSON、YAML等）
   • 首次出现时应展开说明，如：Quick EMUlator (QEMU)

2. 专有名词：

   • cloud-init：带连字符，句首大写
   • datasource：单字形式
   • user-data/vendor-data/cloud-config等：两词+连字符

最佳实践建议

1. 版本控制友好：文档修改应保持清晰的diff记录
2. 可维护性：避免过度依赖图形化内容
3. 国际化考虑：即使使用英文，也应考虑非母语读者的理解难度
4. 技术准确性：所有技术描述应与代码实现保持一致

通过遵循这些规范，cloud-init 项目维护了一个专业、一致且易于维护的文档体系，既方便了开发者协作，也提升了最终用户的使用体验。

cloud-init Official upstream for the cloud-init: cloud instance initialization 项目地址: https://gitcode.com/gh_mirrors/cl/cloud-init