Alluxio技术文档编写规范指南

Alluxio技术文档编写规范指南

alluxio Alluxio, data orchestration for analytics and machine learning in the cloud 项目地址: https://gitcode.com/gh_mirrors/al/alluxio

前言

在开源分布式存储系统Alluxio的生态中，高质量的技术文档对于用户理解和正确使用系统至关重要。本文旨在为Alluxio技术文档贡献者提供一套专业的写作规范，确保文档内容准确、简洁且风格统一。

文档质量四要素（4C原则）

1. 正确性（Correctness）

技术文档的首要原则是确保内容准确无误：

• 所有技术描述必须与系统实际行为一致
• 使用拼写检查工具避免拼写错误
• 专有名词和缩写规范：
  • 缩写词全大写（如AWS、TTL、UFS）
  • 专有名词首字母大写（如Alluxio、Hadoop）

2. 简洁性（Conciseness）

技术文档应避免冗长，直击要点：

• 使用命令式语气：
  • 正确："运行命令启动进程"
  • 错误："接下来，您可以运行命令来启动进程"
• 采用主动语态：
  • 正确："配置错误会导致进程失败"
  • 错误："当配置错误时，进程将会失败"
• 减少无意义的连接词：
  • 避免使用"例如"、"然而"、"首先"等过渡词

3. 一致性（Consistency）

保持术语和表达方式统一：

• 技术术语使用规范（见后文术语对照表）
• 代码相关文本使用反引号标注：
  • 文件路径
  • 属性键值
  • Bash命令及参数
• 代码块标注语言类型：
  • Java代码：```java
  • 属性文件：```properties
  • Shell交互：```console
• Alluxio特定概念前加"the"：
  • "数据将被复制到the Alluxio storage中"
  • "当新文件添加到the Alluxio namespace时"

4. 正式性（Formality）

技术文档应采用专业书面语：

• 使用牛津逗号（序列逗号）：
  • "Alluxio支持Amazon S3、Apache HDFS和Microsoft Azure Object Store"
• 避免缩写：
  • 使用"do not"而非"don't"
• 句子间保持单空格
• 避免口语化表达

核心术语规范表

| 正确术语 | 应避免的术语 | |---------|-------------| | 文件系统 | Filesystem | | 主控节点 | Leader/主Master | | 备用节点 | 备份Master/从节点 | | 容器化 | Docker化 | | 超级用户 | Super-user/超级用户 | | I/O | i/o/IO | | 高可用模式 | 容错模式 | | 主机名 | Host name |

技术文档排版规范

• 分行规则：每个句子单独成行，便于代码审查时查看差异
• 行长限制：虽然没有严格限制，但建议避免单行过长导致需要水平滚动

写作技巧建议

1. 面向不同读者群体：

   • 新手用户：提供更多背景说明和基础概念
   • 高级用户：侧重技术细节和最佳实践

2. 示例驱动：

   • 每个重要功能点都应配有实际使用示例
   • 示例代码应完整且可直接运行

3. 版本适配：

   • 明确标注特性适用的版本范围
   • 对过时功能进行标记并推荐替代方案

4. 故障排除：

   • 常见问题单独设立章节
   • 提供错误现象、原因分析和解决方案

结语

遵循这些规范将帮助创建专业、易用的Alluxio技术文档。良好的文档不仅能降低用户的学习成本，也能减少维护团队的答疑负担。建议文档贡献者在提交前进行内容自查，确保内容符合这些基本原则。

alluxio Alluxio, data orchestration for analytics and machine learning in the cloud 项目地址: https://gitcode.com/gh_mirrors/al/alluxio