文档风格指南

本指南提供的是指导方针，而非硬性规定。虽然这些指导方针值得遵循，但它们并非一成不变的规则。在创作内容时，运用自己的判断和裁量很重要，必要时可以偏离这些指导方针，以提升内容的质量和有效性。归根结底，目标是创作出清晰、简洁且对读者有用的内容，而有时为了实现这一目标，可能需要对指导方针做一些变通。

目标

• 源文本文件易于阅读且便于移植
• 源图文件可编辑
• 源文件在时间和社区跨度上都易于维护

通用风格

• 文本使用 ReStructuredText 或 Markdown 格式，避免使用 HTML 变通写法
• 使用 draw.io 绘制或编辑图像，并导出为 PNG 以便在文档中引用。拉取请求应同时提交这两者
• 在同一页首次出现后，用 Kyuubi 代替 Apache Kyuubi
• 每行字符数上限：78，不可断行的内容除外
• 优先使用列表而非表格
• 优先使用无序列表而非有序列表

ReStructuredText

标题

• 使用 帕斯卡命名法（Pascal Case），每个单词首字母大写，例如 ‘Documentation Style Guide’
• 最多使用 三个层级

• 出现 H4 时，应拆分为多个文件
• 优先使用 `directive rubric`_ 而非 H4

• 使用仅带下划线的修饰样式，不要使用上划线

• 下划线字符的长度应当与标题长度一致
• H1 应使用 ‘=’ 作为下划线
• H2 应使用 ‘-’ 作为下划线
• H3 应使用 ‘~’ 作为下划线
• H4 应使用 ‘^’ 作为下划线，但最好避免使用 H4

• 不要为章节编号
• 标题中尽量不要出现 “Kyuubi”

链接

• 使用简短的描述性短语定义链接，并将它们集中在文件底部

注意

推荐做法

Please refer to `Apache Kyuubi Home Page`_.

.. _Apache Kyuubi Home Page: https://kyuubi.apache.org/

不推荐

Please refer to `Apache Kyuubi Home Page <https://kyuubi.apache.org/>`_.

Markdown

标题

• 使用 帕斯卡命名法（Pascal Case），每个单词首字母大写，例如「Documentation Style Guide」
• 最多使用 三级

• 出现 H4 标题时，请拆分为多个文件

• 请勿 为章节使用编号
• 请勿 在标题中使用「Kyuubi」，除非必要

图片

仅当图片能够直观地解释那些难以用文字表达的信息时，才使用图片。

第三方参考

如果上述参考没有提供明确的指导，请根据你的问题性质参阅以下第三方参考资料：

• Google 开发者文档风格
• Apple 风格指南
• Red Hat 产品文档补充风格指南