尧图网站建设 
CANN开源社区文档写作规范详解从目录规划到质量合规的完整指南【免费下载链接】community本项目是CANN开源社区的核心管理仓库包含社区的治理章程、治理组织、通用操作指引及流程规范等基础信息项目地址: https://gitcode.com/cann/community本文档面向所有参与 CANN 社区开源项目文档工作的开发者系统讲解 CANN 社区文档写作规范 的核心要求涵盖文档内容构成、目录结构规划、写作元素规范、编码格式与贡献合规五个层面。阅读本文后你将掌握一套可直接落地的 CANN 文档写作方法论能够为算子、工具链、组件等各类开源仓编写风格统一、结构清晰、易于检索和引用的高质量 Markdown 文档并通过社区文档门禁与合规检查。规范定位与适用范围《文档写作规范》即 contributor/docs/document_writing_specs.md是 CANN 组织下所有开源项目文档的统一标准覆盖内容、目录、元素和质量合规四类要求目标是确保社区内所有文档风格一致、结构清晰、易于使用。该规范在社区流程中的落地位置可以从两个入口看到在 PR 操作指南 的“开发注意事项”表格中文档类提交被明确指向本文档与安全设计、C 编程规范、安全编码规范、片段引用指导等并列是提交文档类 PR 前必须阅读的基础规范在 新建仓与仓开放操作指引 的指导文档清单中同样将本文档列为建仓后必须遵循的文档要求。此外该规范与 CANN 开源仓英文化指导规范 配套使用前者规定中文文档怎么写后者规定英文文档如何翻译与存放。开发者在写中文文档时即应遵循本规范的目录与命名约定如docs/zh、docs/en、_en后缀规则可为后续英文化减少返工。文档内容要求必选与可选每个开源项目的文档集需要包含以下必选内容标题可以根据项目特点微调内容项说明概述介绍项目的功能、架构与关键特性编译安装提供完整的源码编译与构建指南本地验证指导如何通过简单样例验证基础功能贡献指南说明如何参与项目贡献许可证声明项目遵循的开源许可协议各开源项目还可以根据实际情况补充可选内容包括但不限于样例使用指导examples 的功能说明、编译执行步骤与结果示例等参考文档相关产品文档、培训视频等资源的链接定制开发指导基于项目源码进行二次开发的指南等API 参考开放的接口说明。从仓库现有文档可以看出这套要求的实际落点例如 Ascend C SIG 的 README 在开头即给出项目概述与总体逻辑架构图随后列出工作目标、仓库清单、路标与社区运作方式ops-basic SIG 的贡献指南 则完整覆盖了贡献场景说明、提交 PR 的检查项交付件完整性、关联 Issue、CLA 签署、触发门禁等“贡献指南”内容。新建仓库的文档集可参照 仓库开源条件与目录结构指引 逐项核对。目录结构规范总体原则文档目录组织遵循四条规则统一归档单一项目的多个工具/组件文档统一存放于docs目录下并按子目录分类管理中英文分目录docs目录下区分zh中文与en英文子目录少量文档用后缀区分若文档数量较少如单个算子可不区分zh/en目录采用文件后缀区分——英文文件加_en后缀中文文件无后缀例如aclnnAbs.md与aclnnAbs_en.md强关联文档就近归档与代码强关联的文档如 examples、算子说明直接归档在对应代码目录下。API 文档目录规划API 文档的目录规划有三条规则一文件一接口每个 API 或每个类对应一个 markdown 文件单个项目内部保持规划统一必须有索引API 文档必须提供目录索引文件如README.md或xx_list.md名字可自定义API 数量多时索引文件应置于 API 文件的上层目录分类用子目录若 API 按框架、组件、语言等分类须通过子目录区分。以下四种目录结构示例覆盖了从简到繁的典型场景示例1平铺结构文档较少 |-- xx_list.md |-- api1.md |-- api2.md |-- api3.md 示例2索引文件外提 |-- xx_list.md |-- context |--|-- api1.md |--|-- api2.md |--|-- api3.md |--|-- ... 示例3多语言API |-- c_api |--|-- c_list.md |--|-- context |--|--|-- api1.md |--|--|-- api2.md |--|--|-- ... |-- python_api |--|-- python_list.md |--|-- context |--|--|-- api1.md |--|--|-- api2.md |--|--|-- ... 示例4统一索引按功能特性分组 |-- api_list.md |--|-- feature1 |--|--|-- api1.md |--|--|-- api2.md |--|--|-- api3.md |--|-- feature2 |--|--|-- api1.md |--|--|-- api2.md |--|--|-- api3.md |--|-- feature3 |--|--|-- api1.md |--|--|-- api2.md |--|--|-- api3.md规划建议文档数量少时优先采用示例 1 或 2 的平铺/外提结构存在多语言 API 或功能特性分组需求时使用示例 3 或 4 的分级结构保证索引入口唯一、层级不超过三层便于搜索引擎与开发者快速定位。内容元素规范文件命名新增文档需在对应目录下新增 Markdown 文件以.md结尾并遵循以下规则文件名使用英文小写命名多个单词用**下划线_**连接文件名不宜过长建议不超过 50 个字符README 文档中文命名为README.md英文命名为README_en.md同一目录下不能出现重名文件。英文文档的存放模式与_en后缀的详细规则并列存放 vs 分目录存放、切换按钮格式等参见 CANN 开源仓英文化指导规范。标题标题规则的核心是“简洁、一致、无编号、逐级递增”标题应简洁明了概括章节核心内容操作类标题使用动宾结构例如“申请权限”同级别同类型标题结构保持一致标题末尾不加标点避免使用特殊字符如“?”补充说明使用圆括号标题与正文间空一行标题使用#[空格][标题名]格式级别需逐级递增第一个标题应是顶层标题标题中不能手工添加序号例如 “## 1. 安装CANN” 需修改为 “## 安装CANN”标题建议最多四级。# 一级标题 ## 二级标题 ### 三级标题 #### 四级标题字体样式斜体使用一个星号*表示如*斜体文本*粗体使用两个星号**表示如**粗体文本**粗斜体使用 3 个星号***表示如***粗斜体文本***转义对特定内容使用转义符\如\转义的标记符号\。图片图片是技术文档中解释界面、架构、运行结果的关键元素CANN 文档对图片的引用提出如下规则图片以英文小写命名多个单词用下划线_连接名称不宜过长建议不超过 50 个字符图片统一存放到文档同级目录下的figures文件夹中使用相对路径引用使用原创图片避免侵权图文配合使用切忌图文分离格式首选 PNG次选 JPG中/英文文档须分别使用对应语言的插图截图应只保留核心内容关键信息可用红框或文字标注确保图片清晰可辨。图片插入的标准格式如下alt 属性文本 alt 属性文本 示例  或 [!NOTE]说明 仓库中 PR 操作指南 使用figures/contri-flow.png、社区 CANN 测试报告 使用assets/目录组织图片均遵循“图片就近存放、相对路径引用”的原则。代码块代码块规范强调可运行与可读性确保代码的逻辑和语法正确清晰区分输入与输出部分关键步骤须有注释说明行内代码和命令行使用 1 对反引号如行内代码块级代码使用 3 个反引号并声明语言类型上下空一行。常见语言类型包括python、c、c、markdown、bash、ini、yaml、json、xml、html、java、javascript、php、sql、ruby 等。行内代码 printf() 函数 块级代码 c #include stdio.h int main(void) { printf(Hello world\n); }#!/usr/bin/env python3 print(Hello, World!);输出Hello, World!说明块级代码示例中需将外层 text 替换为对应的 c/python/text 语言标识 ### 列表 列表选择原则有明显先后逻辑顺序使用**有序列表**并列关系、多选一情况使用**无序列表**。标点规则列表项为术语、短语时统一不加标点为完整句子时统一加句号混合情况下统一加句号前几项以分号结尾、最后一项以句号结尾的形式也可以接受。 - **无序列表**使用星号\*、加号或减号-作为标记标记后添加一个空格再填写内容一个文件中的同一个无序列表建议使用同一个符号 - **有序列表**使用数字加句点.表示不支持使用字母如 a、b、c作为序号 - **嵌套列表**列表嵌套只需在子列表项前添加两个或四个空格**不要使用 tab 键**。 text * 第一项 * 第二项 * 第三项 1. 第一项 - 第一项嵌套的第一个元素 - 第一项嵌套的第二个元素 2. 第二项 - 第二项嵌套的第一个元素 - 第二项嵌套的第二个元素注释符号文档中的注释符号用于表示提示的重要程度共分三级符号语义适用场景说明NOTE提供辅助性提示或参考信息补充解释、背景知识注意CAUTION如未按此操作可能导致任务中断或结果异常可恢复操作步骤中的关键提醒警告WARNING如不避免可能导致轻微或中度伤害涉及安全风险的提示 [!NOTE]说明 正文 [!CAUTION]注意 正文 [!WARNING]警告 正文写作要点根据使用场景选择恰当的注释符号注释块内可嵌套有序/无序列表但不建议放表格和代码块使用连续的符号以保证样式不中断说明/注意等样式中内容应简洁过长可迁移至正文或分段处理。链接确保链接目标有效避免死链引用文档时建议用书名号包裹并添加超链接。- 网站链接 AA的安装步骤请参考[《安装与部署》](https://www.aa.com)。 - 相对路径 文档开发流水线门禁锚点引用文档内标题、图片或表格时请使用锚点。两种设置方法方法一将标题中大写字母转换为小写空格替换为中划线-并去除特殊符号方法二添加a标签在a标签中自定义锚点 ID。# 安装前准备 A* 这是CANN的安装前准备。 ... 参考[安装前准备](#安装前准备-a)章节。 **图1** CI 检查结果 CI 检查结果a idfig11/a ... 参考图1[CI 检查结果](#fig11)。表格使用标准 markdown 表格语法若无特殊格式诉求不建议使用 HTML 表格表格内一列全部是术语、短语时统一不加标点为句子时统一加句号混合情况下统一加句号。| 表头1 | 表头2 | | ------- | ------- | | 单元格1 | 单元格2 | | 单元格4 | 单元格4 |对齐方式设置--:设置内容和标题栏居右对齐:--设置内容和标题栏居左对齐:--:设置内容和标题栏居中对齐。标点符号单位与数字、中文与英文、中文与中文之间不加空格比如50m10kg64Kbit/s昇腾AI处理器。例外情况产品名称例如Atlas 350 加速卡Atlas 800T A3 超节点服务器“”、“~”、“”和“”符号前后加空格例如1Byte 8bit列表项标点使用保持一致中文文档使用全角标点数字使用半角字符感叹号仅用于可能引发严重人身或设备安全后果的警告引用其他文档时添加书名号并建议增加引用文档的跳转链接。从仓库实例看SIG 贡献指南 中“提交 PR 时请按照PR模板仔细填写本次PR的业务背景、目的、方案等信息”等表述即遵循了“中文文档使用全角标点、英文单词与中文之间不加空格”的排版要求。文件编码格式要求Markdown 文件必须使用UTF-8 编码格式该编码支持所有语言字符跨平台兼容性好不可使用 UTF-8 with BOM编码格式此格式会在文件开头添加 3 个冗余字符EF BB BF可能造成不同平台上的显示异常。贡献合规要求文档贡献同样受社区合规约束提交内容必须是与 CANN 特性相关的内容内容不能包含敏感信息、有强烈的种族歧视或性别歧视的内容提交的内容必须是原创内容不得侵犯他人知识产权提交的内容必须客观、真实不允许使用夸大宣传等词汇。文档贡献中不受欢迎的行为短时间内通过自动化工具提交大量的 issue诸如拼写错误、语法错误、日期错误、语句不通顺等“无害错误”的修正。合规审查与写作检查在实际流程中的衔接点包括文档 PR 需通过开源仓门禁如compile指令触发的 codecheck可参考 SIG 贡献指南 中的 PR 提交流程文档类提交须关联对应 Issue如Documentation|文档反馈类型流程详见 PR 操作指南英文化文档需通过 Doc Tools 的 markdownlint、HTML 标签闭合、链接有效性、资源有效性等四项检查详见 CANN 开源仓英文化指导规范测试类文档如版本测试报告可参考 测试报告模板 的章节组织方式与本文档的表格、标题规范配合使用。写作自检清单完成一篇 CANN 文档后建议按以下清单逐项自检内容完整性是否覆盖概述、编译安装、本地验证、贡献指南、许可证五项必选内容按项目特点微调目录合规多组件文档是否归档在docs下并按zh/en分目录少量文档是否使用_en后缀区分API 文档是否提供索引文件命名规范文件名是否英文小写、下划线连接、不超过 50 字符标题规范是否无手工序号、无末尾标点、级别逐级递增、最多四级元素规范代码块是否声明语言类型并带注释列表/表格标点是否统一注释符号选用是否恰当图片规范图片是否存放于同级figures目录、相对路径引用、PNG/JPG 格式、图文配合编码合规文件是否 UTF-8 无 BOM 编码内容合规内容是否原创、客观、与 CANN 特性相关、无敏感与夸大表述遵循以上规范产出的文档不仅能在 CANN 社区内保持一致的风格与质量也能让搜索引擎、Agent 与 LLM 更准确地理解、检索和引用其中的技术信息。【免费下载链接】community本项目是CANN开源社区的核心管理仓库包含社区的治理章程、治理组织、通用操作指引及流程规范等基础信息项目地址: https://gitcode.com/cann/community创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 CANN开源社区文档写作规范详解：从目录规划到质量合规的完整指南
CANN开源社区文档写作规范详解从目录规划到质量合规的完整指南【免费下载链接】community本项目是CANN开源社区的核心管理仓库包含社区的治理章程、治理组织、通用操作指引及流程规范等基础信息项目地址: https://gitcode.com/cann/community本文档面向所有参与 CANN 社区开源项目文档工作的开发者系统讲解 CANN 社区文档写作规范 的核心要求涵盖文档内容构成、目录结构规划、写作元素规范、编码格式与贡献合规五个层面。阅读本文后你将掌握一套可直接落地的 CANN 文档写作方法论能够为算子、工具链、组件等各类开源仓编写风格统一、结构清晰、易于检索和引用的高质量 Markdown 文档并通过社区文档门禁与合规检查。规范定位与适用范围《文档写作规范》即 contributor/docs/document_writing_specs.md是 CANN 组织下所有开源项目文档的统一标准覆盖内容、目录、元素和质量合规四类要求目标是确保社区内所有文档风格一致、结构清晰、易于使用。该规范在社区流程中的落地位置可以从两个入口看到在 PR 操作指南 的“开发注意事项”表格中文档类提交被明确指向本文档与安全设计、C 编程规范、安全编码规范、片段引用指导等并列是提交文档类 PR 前必须阅读的基础规范在 新建仓与仓开放操作指引 的指导文档清单中同样将本文档列为建仓后必须遵循的文档要求。此外该规范与 CANN 开源仓英文化指导规范 配套使用前者规定中文文档怎么写后者规定英文文档如何翻译与存放。开发者在写中文文档时即应遵循本规范的目录与命名约定如docs/zh、docs/en、_en后缀规则可为后续英文化减少返工。文档内容要求必选与可选每个开源项目的文档集需要包含以下必选内容标题可以根据项目特点微调内容项说明概述介绍项目的功能、架构与关键特性编译安装提供完整的源码编译与构建指南本地验证指导如何通过简单样例验证基础功能贡献指南说明如何参与项目贡献许可证声明项目遵循的开源许可协议各开源项目还可以根据实际情况补充可选内容包括但不限于样例使用指导examples 的功能说明、编译执行步骤与结果示例等参考文档相关产品文档、培训视频等资源的链接定制开发指导基于项目源码进行二次开发的指南等API 参考开放的接口说明。从仓库现有文档可以看出这套要求的实际落点例如 Ascend C SIG 的 README 在开头即给出项目概述与总体逻辑架构图随后列出工作目标、仓库清单、路标与社区运作方式ops-basic SIG 的贡献指南 则完整覆盖了贡献场景说明、提交 PR 的检查项交付件完整性、关联 Issue、CLA 签署、触发门禁等“贡献指南”内容。新建仓库的文档集可参照 仓库开源条件与目录结构指引 逐项核对。目录结构规范总体原则文档目录组织遵循四条规则统一归档单一项目的多个工具/组件文档统一存放于docs目录下并按子目录分类管理中英文分目录docs目录下区分zh中文与en英文子目录少量文档用后缀区分若文档数量较少如单个算子可不区分zh/en目录采用文件后缀区分——英文文件加_en后缀中文文件无后缀例如aclnnAbs.md与aclnnAbs_en.md强关联文档就近归档与代码强关联的文档如 examples、算子说明直接归档在对应代码目录下。API 文档目录规划API 文档的目录规划有三条规则一文件一接口每个 API 或每个类对应一个 markdown 文件单个项目内部保持规划统一必须有索引API 文档必须提供目录索引文件如README.md或xx_list.md名字可自定义API 数量多时索引文件应置于 API 文件的上层目录分类用子目录若 API 按框架、组件、语言等分类须通过子目录区分。以下四种目录结构示例覆盖了从简到繁的典型场景示例1平铺结构文档较少 |-- xx_list.md |-- api1.md |-- api2.md |-- api3.md 示例2索引文件外提 |-- xx_list.md |-- context |--|-- api1.md |--|-- api2.md |--|-- api3.md |--|-- ... 示例3多语言API |-- c_api |--|-- c_list.md |--|-- context |--|--|-- api1.md |--|--|-- api2.md |--|--|-- ... |-- python_api |--|-- python_list.md |--|-- context |--|--|-- api1.md |--|--|-- api2.md |--|--|-- ... 示例4统一索引按功能特性分组 |-- api_list.md |--|-- feature1 |--|--|-- api1.md |--|--|-- api2.md |--|--|-- api3.md |--|-- feature2 |--|--|-- api1.md |--|--|-- api2.md |--|--|-- api3.md |--|-- feature3 |--|--|-- api1.md |--|--|-- api2.md |--|--|-- api3.md规划建议文档数量少时优先采用示例 1 或 2 的平铺/外提结构存在多语言 API 或功能特性分组需求时使用示例 3 或 4 的分级结构保证索引入口唯一、层级不超过三层便于搜索引擎与开发者快速定位。内容元素规范文件命名新增文档需在对应目录下新增 Markdown 文件以.md结尾并遵循以下规则文件名使用英文小写命名多个单词用**下划线_**连接文件名不宜过长建议不超过 50 个字符README 文档中文命名为README.md英文命名为README_en.md同一目录下不能出现重名文件。英文文档的存放模式与_en后缀的详细规则并列存放 vs 分目录存放、切换按钮格式等参见 CANN 开源仓英文化指导规范。标题标题规则的核心是“简洁、一致、无编号、逐级递增”标题应简洁明了概括章节核心内容操作类标题使用动宾结构例如“申请权限”同级别同类型标题结构保持一致标题末尾不加标点避免使用特殊字符如“?”补充说明使用圆括号标题与正文间空一行标题使用#[空格][标题名]格式级别需逐级递增第一个标题应是顶层标题标题中不能手工添加序号例如 “## 1. 安装CANN” 需修改为 “## 安装CANN”标题建议最多四级。# 一级标题 ## 二级标题 ### 三级标题 #### 四级标题字体样式斜体使用一个星号*表示如*斜体文本*粗体使用两个星号**表示如**粗体文本**粗斜体使用 3 个星号***表示如***粗斜体文本***转义对特定内容使用转义符\如\转义的标记符号\。图片图片是技术文档中解释界面、架构、运行结果的关键元素CANN 文档对图片的引用提出如下规则图片以英文小写命名多个单词用下划线_连接名称不宜过长建议不超过 50 个字符图片统一存放到文档同级目录下的figures文件夹中使用相对路径引用使用原创图片避免侵权图文配合使用切忌图文分离格式首选 PNG次选 JPG中/英文文档须分别使用对应语言的插图截图应只保留核心内容关键信息可用红框或文字标注确保图片清晰可辨。图片插入的标准格式如下alt 属性文本 alt 属性文本 示例  或 [!NOTE]说明 仓库中 PR 操作指南 使用figures/contri-flow.png、社区 CANN 测试报告 使用assets/目录组织图片均遵循“图片就近存放、相对路径引用”的原则。代码块代码块规范强调可运行与可读性确保代码的逻辑和语法正确清晰区分输入与输出部分关键步骤须有注释说明行内代码和命令行使用 1 对反引号如行内代码块级代码使用 3 个反引号并声明语言类型上下空一行。常见语言类型包括python、c、c、markdown、bash、ini、yaml、json、xml、html、java、javascript、php、sql、ruby 等。行内代码 printf() 函数 块级代码 c #include stdio.h int main(void) { printf(Hello world\n); }#!/usr/bin/env python3 print(Hello, World!);输出Hello, World!说明块级代码示例中需将外层 text 替换为对应的 c/python/text 语言标识 ### 列表 列表选择原则有明显先后逻辑顺序使用**有序列表**并列关系、多选一情况使用**无序列表**。标点规则列表项为术语、短语时统一不加标点为完整句子时统一加句号混合情况下统一加句号前几项以分号结尾、最后一项以句号结尾的形式也可以接受。 - **无序列表**使用星号\*、加号或减号-作为标记标记后添加一个空格再填写内容一个文件中的同一个无序列表建议使用同一个符号 - **有序列表**使用数字加句点.表示不支持使用字母如 a、b、c作为序号 - **嵌套列表**列表嵌套只需在子列表项前添加两个或四个空格**不要使用 tab 键**。 text * 第一项 * 第二项 * 第三项 1. 第一项 - 第一项嵌套的第一个元素 - 第一项嵌套的第二个元素 2. 第二项 - 第二项嵌套的第一个元素 - 第二项嵌套的第二个元素注释符号文档中的注释符号用于表示提示的重要程度共分三级符号语义适用场景说明NOTE提供辅助性提示或参考信息补充解释、背景知识注意CAUTION如未按此操作可能导致任务中断或结果异常可恢复操作步骤中的关键提醒警告WARNING如不避免可能导致轻微或中度伤害涉及安全风险的提示 [!NOTE]说明 正文 [!CAUTION]注意 正文 [!WARNING]警告 正文写作要点根据使用场景选择恰当的注释符号注释块内可嵌套有序/无序列表但不建议放表格和代码块使用连续的符号以保证样式不中断说明/注意等样式中内容应简洁过长可迁移至正文或分段处理。链接确保链接目标有效避免死链引用文档时建议用书名号包裹并添加超链接。- 网站链接 AA的安装步骤请参考[《安装与部署》](https://www.aa.com)。 - 相对路径 文档开发流水线门禁锚点引用文档内标题、图片或表格时请使用锚点。两种设置方法方法一将标题中大写字母转换为小写空格替换为中划线-并去除特殊符号方法二添加a标签在a标签中自定义锚点 ID。# 安装前准备 A* 这是CANN的安装前准备。 ... 参考[安装前准备](#安装前准备-a)章节。 **图1** CI 检查结果 CI 检查结果a idfig11/a ... 参考图1[CI 检查结果](#fig11)。表格使用标准 markdown 表格语法若无特殊格式诉求不建议使用 HTML 表格表格内一列全部是术语、短语时统一不加标点为句子时统一加句号混合情况下统一加句号。| 表头1 | 表头2 | | ------- | ------- | | 单元格1 | 单元格2 | | 单元格4 | 单元格4 |对齐方式设置--:设置内容和标题栏居右对齐:--设置内容和标题栏居左对齐:--:设置内容和标题栏居中对齐。标点符号单位与数字、中文与英文、中文与中文之间不加空格比如50m10kg64Kbit/s昇腾AI处理器。例外情况产品名称例如Atlas 350 加速卡Atlas 800T A3 超节点服务器“”、“~”、“”和“”符号前后加空格例如1Byte 8bit列表项标点使用保持一致中文文档使用全角标点数字使用半角字符感叹号仅用于可能引发严重人身或设备安全后果的警告引用其他文档时添加书名号并建议增加引用文档的跳转链接。从仓库实例看SIG 贡献指南 中“提交 PR 时请按照PR模板仔细填写本次PR的业务背景、目的、方案等信息”等表述即遵循了“中文文档使用全角标点、英文单词与中文之间不加空格”的排版要求。文件编码格式要求Markdown 文件必须使用UTF-8 编码格式该编码支持所有语言字符跨平台兼容性好不可使用 UTF-8 with BOM编码格式此格式会在文件开头添加 3 个冗余字符EF BB BF可能造成不同平台上的显示异常。贡献合规要求文档贡献同样受社区合规约束提交内容必须是与 CANN 特性相关的内容内容不能包含敏感信息、有强烈的种族歧视或性别歧视的内容提交的内容必须是原创内容不得侵犯他人知识产权提交的内容必须客观、真实不允许使用夸大宣传等词汇。文档贡献中不受欢迎的行为短时间内通过自动化工具提交大量的 issue诸如拼写错误、语法错误、日期错误、语句不通顺等“无害错误”的修正。合规审查与写作检查在实际流程中的衔接点包括文档 PR 需通过开源仓门禁如compile指令触发的 codecheck可参考 SIG 贡献指南 中的 PR 提交流程文档类提交须关联对应 Issue如Documentation|文档反馈类型流程详见 PR 操作指南英文化文档需通过 Doc Tools 的 markdownlint、HTML 标签闭合、链接有效性、资源有效性等四项检查详见 CANN 开源仓英文化指导规范测试类文档如版本测试报告可参考 测试报告模板 的章节组织方式与本文档的表格、标题规范配合使用。写作自检清单完成一篇 CANN 文档后建议按以下清单逐项自检内容完整性是否覆盖概述、编译安装、本地验证、贡献指南、许可证五项必选内容按项目特点微调目录合规多组件文档是否归档在docs下并按zh/en分目录少量文档是否使用_en后缀区分API 文档是否提供索引文件命名规范文件名是否英文小写、下划线连接、不超过 50 字符标题规范是否无手工序号、无末尾标点、级别逐级递增、最多四级元素规范代码块是否声明语言类型并带注释列表/表格标点是否统一注释符号选用是否恰当图片规范图片是否存放于同级figures目录、相对路径引用、PNG/JPG 格式、图文配合编码合规文件是否 UTF-8 无 BOM 编码内容合规内容是否原创、客观、与 CANN 特性相关、无敏感与夸大表述遵循以上规范产出的文档不仅能在 CANN 社区内保持一致的风格与质量也能让搜索引擎、Agent 与 LLM 更准确地理解、检索和引用其中的技术信息。【免费下载链接】community本项目是CANN开源社区的核心管理仓库包含社区的治理章程、治理组织、通用操作指引及流程规范等基础信息项目地址: https://gitcode.com/cann/community创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考