研发文档编写规范
目的
为了统一公司产品研发文档的编写风格，提高文档的可读性，减少不必要的沟通成本，特别是确保对外输出高质量的产品客户/用户文档，同时保证各个产线文档风格的一致性，为公司建立品牌提供支持。
范围
适用于研发过程及发布输出的各类文档，整体分为 面向内部研发团队 和 面向客户/用户相关方 两大类文档。
面向内部研发团队的文档包括：
- 需求规格说明书，SRS（Software Requirement Specification）
- 技术设计方案
- 远景范围文件
- 风险评估文件
- 项目结构文件
面向客户/用户相关方的文档包括：
- 厂商手册
- 用户手册
- 编程手册
术语和定义
- DocFX: 微软公司推出的针对研发文档的组织软件。
- toc.yml 文件：指 DocFX 中组织文档目录的配置文件。
- 规则：进⾏文档编写时必须遵守的规定，文档内容不符合 规则，则评审不通过。
- 原则：进行文档编写时应该遵守的基本要求，原则 具备通用适应性，但是允许个案的特殊性。
- 说明：对此规则或原则的必要解释，确保对于 规则 和 原则 的理解一致。
- 正例：对此规则给出正确例⼦。
- 反例：对此规则给出反⾯例⼦。
- 例外：对此规则给出例外的说明。
具体规范
《研发文档编写规范》明确定义了文档管理的基本要求，原则上都要遵守。《研发文档编写指南》是《研发文档编写规范》的参考手册。
文档命名
基于产品文档面向的对象及专业技能的不同，产品的用户文档分为三大类，即厂商手册、用户手册和编程手册，以下规则定义三种类型的文件命名。
【规则】：厂商手册 需按照 {XXX型号}+{系统名称}+数控系统厂商手册+Rn 格式命名。
案例及说明：
- 运动控制卡系列：运动控制卡型号+系统名称+“数控系统厂商手册”+Rn，例如：PM95A玻璃切割数控系统厂商手册-R1
- 工业计算机系列：工业计算机型号+系统名称+“数控系统厂商手册”+Rn，例如：NC60A义齿机数控系统厂商手册-R1
- 一体机系列：一体机型号+系统名称+“集成数控系统厂商手册”+ Rn，例如：NK280B外圆磨床集成数控系统厂商手册- R1
【规则】：用户手册 需按照 {软件名称}+{系统名称}+“控制系统用户手册”+Rn 格式命名。
案例及说明：用户手册 面向机床加工操作人员 ，内容主要关注数控软件的功能操作步骤、驱动器参数介绍及其调试。一般包括软件用户手册和驱动器软件及参数用户手册。
控制系统类软件：软件名称+系统名称+ “控制系统用户手册”，例如： NcStudio Phoenix 石材加工中心控制系统
驱动器：维智 WSDA 系列直线伺服驱动器用户手册（脉冲型）-R1；iMotion 操作手册-R3
【规则】：编程手册 需按照{软件名称}+“编程手册”+“-Rn”
案例及说明：
NcStudio 编程手册-R1
其它类型的文档命名定义待讨论。
文档组织
【规则】 文档格式必须统一使用 Markdown 文件。
说明：Markdown 文档作为纯文本编辑格式，易读易写，其本质是让我们回归到内容本身，注重文章本身的结构，而不是样式，同时可以让文档像代码一样进行版本管理。
【原则】 文档编辑工具原则上要使用 VS Code 工具，并确保安装插件 Learn Authoring Pack。
说明：统一工具是为了保证团队工作环境的一致性，且该插件提供了 Markdown 的检查机制，对于不符合格式要求的，则默认会有黄色波浪线提示。
【规则】 文档发布及展示必须统一使用 DocFX 工具，文档目录结构组织统一由 DocFX 的配置文件 toc.yml 进行控制，因此不对目录进行编号。
说明：为了更好的保证文档的生成及展示，也为了帮助团队对文档形式上统一认识，避免产生在文档形式上的纠结，文档统一通过 DocFX 工具发布及展示。
文档内容
【原则】 编写文档内容需根据《产品研发文档编写指南》定义的 内容及格式 章节。
说明： 如有该章节未覆盖到或者和其有冲突的情况，请及时反馈给软件部祁彩云。
【规则】 标题中禁止使用编号，所有文档的标题都必须从一级标题开始，逐级递增使用，不允许跳级。
【规则】 符合 安全标识 约定情况的正文内容应在文档中添加相关标签进行明示。
说明： 为了使阅读者对文中涉及到的安全相关信息或需要关注的信息进行重视，使用警告(WARNING)、注意(CAUTION)和注释(NOTE)等标签标识其在安全或关注方面的重要程度。 详情参考《指南》-> 内容及格式 -> 安全标识 章节。
【原则】 对于图表类的展示， 宜采用 Mermaid 编写。
说明：Mermaid 对各种图表支持较为丰富，并且从工具集考量，目前 VS Code + 插件 Learn Authoring Pack 对 Mermaid 的支持较好。
【原则】：如有涉及到的单个的功能手册、快速上手指南、维宏百问等文档原则上不作为独立的文档，应持续在产品三大手册中更新。
三大手册包括厂商手册、用户手册和编程手册 Q：什么时候需要功能手册？
A：功能手册内容理论上应该归属于用户手册，一般不做单独的文件。但不排除产品维护阶段，需要新增某个单独的功能，用户要求提供具体的功能的手册，可以提供。但也要确保功能及时更新到用户手册。
【原则】：文档内容必须和相应版本的软件保持一致，英文文档涉及到的术语应和语料库一致。
说明： 文档内容要保持及时更新，原则是每次软件升级，文档版本也应该进行升级。 英文文档和中文一样，语料库按需更新。
【规则】：需要印刷的文档最后一章需加上“用户安装软件许可声明”。
说明：部分产线需要印刷文档。