关于开发文档向 Markdown(Docs-as-Code)转型的可行性研究报告

关于开发文档向 Markdown(Docs-as-Code)转型的可行性研究报告

Data ：2026/1/5

作者：HeartJK

版本：Ver1.0

文章目录

• [关于开发文档向 Markdown(Docs-as-Code)转型的可行性研究报告](#关于开发文档向 Markdown(Docs-as-Code)转型的可行性研究报告)
• • [1. 标题](#1. 标题)
  • [2. 背景](#2. 背景)
  • [3. 目的](#3. 目的)
  • • [3.1 Docs-as-Code 核心价值主张 (Core Value Propositions)](#3.1 Docs-as-Code 核心价值主张 (Core Value Propositions))
  • [4. 方法 (Methodology)](#4. 方法 (Methodology))
  • • [4.1 文档格式标准化迁移](#4.1 文档格式标准化迁移)
    • [4.2 文档融入代码工程的版本控制流程](#4.2 文档融入代码工程的版本控制流程)
    • [4.3 标准化表格的清晰呈现 (Structured Tables)](#4.3 标准化表格的清晰呈现 (Structured Tables))
    • [4.4 工程图表的代码化与多样性 (Diagrams as Code)](#4.4 工程图表的代码化与多样性 (Diagrams as Code))
    • [4.5 自动化构建与检查 (CI/CD Pipeline)](#4.5 自动化构建与检查 (CI/CD Pipeline))
    • [4.6 高效的在线审查与发布流程 (Streamlined Review Workflow)](#4.6 高效的在线审查与发布流程 (Streamlined Review Workflow))
  • [5. 结果 (Results)](#5. 结果 (Results))
  • • [5.1 核心成果指标 (Key Outcomes)](#5.1 核心成果指标 (Key Outcomes))
    • [5.2 基于 V 模型的全链路效能提升预测 (V-Model Efficiency Forecast)](#5.2 基于 V 模型的全链路效能提升预测 (V-Model Efficiency Forecast))
  • [6. 考察 (Discussion)](#6. 考察 (Discussion))
  • • [6.1 车载行业标准的合规性 (ASPICE/ISO 26262)](#6.1 车载行业标准的合规性 (ASPICE/ISO 26262))
    • [6.2 信号矩阵处理的局限性](#6.2 信号矩阵处理的局限性)
    • [6.3 团队技能转型](#6.3 团队技能转型)
  • [7. 结论 (Conclusion)](#7. 结论 (Conclusion))

1. 标题

车载软件开发文档向 Markdown (Docs-as-Code) 转型的可行性与实施方案研究

2. 背景

随着"软件定义汽车"趋势的深入，车载软件的复杂度呈指数级上升。目前，我司开发设计文档主要依赖 Microsoft Word 和 Excel 进行编写与管理。在长期的项目实践中，传统文档模式逐渐暴露出以下瓶颈：

• 版本割裂：文档与代码分离存储，导致代码迭代后文档往往更新滞后，出现"两张皮"现象。
• AI 赋能困难：Word/Excel 的二进制格式及复杂的样式标签增加了大语言模型 (LLM) 的解析噪声，不利于后续构建企业级 AI 知识库。
• 评审效率低：无法使用 Diff 工具高效比对文档变更，人工审核大量 Word 文档极其耗时且容易遗漏细节。

3. 目的

本研究旨在评估将设计文档全面转向 Markdown 格式的可行性，并构建一套"文档即代码 (Docs-as-Code)"的工程化流程。具体目标如下：

1. AI 友好化：统一 Input 格式，为后续 AI 辅助分析代码、自动生成测试用例打下数据基础。
2. 研运一体化：将文档纳入代码仓库管理，利用 Git 流程保证设计与代码逻辑的高度一致性。
3. 提升效能：通过自动化工具链（CI/CD）降低文档维护与发布的边际成本。

3.1 Docs-as-Code 核心价值主张 (Core Value Propositions)

除了工具层面的改进，引入 Docs-as-Code 理念将带来深层次的研发范式转移：

• 单一事实来源 (Single Source of Truth)： 代码库（Repository）成为唯一可信源。需求、设计、代码、测试脚本同源存储，彻底解决了"文档在 SVN，代码在 Gerrit，两者版本永远对不上"的顽疾。
• 消除"上下文切换" (Eliminating Context Switching)： 根据 Stack Overflow 开发者调研，频繁切换工具是降低研发效率的首因。Docs-as-Code 允许开发人员在他们最熟悉的 IDE（如 VS Code）中，用编写代码的方式编写文档，在复杂工程中，软件开发人员使用linux或开发机无法查看office或SVN文档，因此无需打开笨重的 Office 软件,保持心流（Flow）状态是必要的
• 文档质量的可测试性 (Testability)： 文档不再是静态死文件，而是可以被"编译"和"测试"的对象。通过 CI 流水线，我们可以自动检测死链、拼写错误、格式规范，甚至验证代码示例的可运行性，像守护代码质量一样守护文档质量。
• 细粒度的可追溯性 (Granular Traceability) ： Word 的修订记录是基于文件的，而 Git 是基于行的。我们可以使用 git blame 精确追溯到某一行需求 是谁 在什么时间 修改的，以及关联了哪一次代码提交（Commit ID），这对于功能安全（ISO 26262）的审计至关重要。
• 高效的审查与交付体验 (Streamlined Review & Delivery)： 相比于 SVN 时代"下载文档 -> 本地打开 -> 查找信息"的繁琐流程，Docs-as-Code 模式支持 SQA 和 Reviewer 直接在 Git 网页端（Merge Request 视图）进行在线查阅和评论。此外，可依赖 CI/CD 自动整合最新版本生成 HTML 页面或通过脚本进行合规性确认，极大提升了验收效率和透明度。
• 卓越的检索与知识发现 (Superior Searchability & Knowledge Discovery) ： 传统 SVN 中的 Office 二进制文档如同"数据孤岛"，难以进行跨文件的全文检索。Markdown 的纯文本特性使得在 VS Code 中进行全库毫秒级关键词搜索成为可能。更重要的是，这种格式天然适配 AI 语义搜索（RAG），使得"查找关于扭矩限制的所有设计说明"这样的自然语言查询成为现实，极大降低了信息获取门槛，同时也为后续AI知识库建立基础。
• 通用行业标准与生态兼容 (Industry Standard & Ecosystem) ： Markdown 已成为全球软件行业的"通用语言"。GitHub, GitLab, Gitee (码云) 等主流代码托管平台均将 Markdown 作为默认的文档展示格式（如 README.md, Wiki, Issue）。采用这一通用标准不仅意味着零厂商锁定 (No Vendor Lock-in)------还能直接复用开源社区丰富的工具链生态，对后续资产库管理等数据处理大幅降低自研成本。
• 多语言支持与翻译友好性 (Translation Friendliness)：Markdown 本质上是纯文本格式，因此与翻译工具和 AI 的兼容性极高。利用 AI 工具，可以轻松地将整个文档快速准确地转换为不同的语言形式，大幅降低全球开发据点之间的信息共享成本。

4. 方法 (Methodology)

4.1 文档格式标准化迁移

鉴于现有项目资产庞大，我们采取"增量优先、存量渐进"的策略，逐步从传统的 Word/Excel 模式过渡到 Markdown，而非立即全面弃用。

• 针对 Word (富文本) ：
  • 新项目/新模块：强制使用 Markdown 编写系统架构与详细设计。
  • 存量文档：维持现状，仅在发生重大架构变更时进行迁移，避免为了迁移而迁移。
• 针对 Excel (表格数据) ：
  • 逻辑类表格（如状态跳转表、简单 API 定义）：转换为 Markdown 表格，以便 Diff 和阅读。
  • 数据类表格 （如 CAN 矩阵、复杂标定参数）：保留 Excel/CSV 格式，但剥离其"说明文档"属性，仅作为数据源文件纳入 Git 管理，供 Markdown 文档引用或脚本读取。

对比展示：

特性	传统 Word/Excel 模式	Markdown 目标模式
存储格式	.docx / .xlsx (二进制)	.md (纯文本) + .csv (结构化数据)
版本对比	依赖 Office 审阅，难以比对	使用 git diff，精确到字符/数据行
AI 可读性	差 (含大量样式噪音)	优 (结构化语义清晰)
迁移策略	现状	渐进式：新项目 MD 化，老项目按需维护

针对Git diff对比，传统Word Excel版本之间只能靠作成者的颜色标识或者更新履历填写情况确认变更点，对于markdown格式可以通过git diff之间查看变更范围，效果如下

4.2 文档融入代码工程的版本控制流程

建立文档与代码"同仓共存、同频发布"的协作机制。开发人员在提交代码 (Commit) 时，必须包含对应的 Markdown 文档修改。我们推荐采用 "根目录独立存放" 的策略，即在工程根目录下建立 docs/ 目录。

目录结构策略：从 SVN 阶段导向到 Git 模块导向

在 SVN 时代，文档通常按研发阶段存放（如 RD/, SD/, MD/），这符合瀑布流交付。但在 Docs-as-Code 模式下，我们推荐 "按模块垂直切分 (Module-based)"，仅系统级文档保留分层结构。

• 系统级文档 (System Level)：对应原 SD 阶段的整体设计，依然按层级存放。
• 模块级文档 (Component Level) ：对应原 MD 阶段及模块级 RD，全部聚合在模块目录下。

推荐的仓库目录结构：

Project_Root/               # Git 仓库根目录
├── src/                    # [Code] 源代码目录，下级目录为示例，按照正常工程code层级即可
│   ├── main.c              #system
│   ├── Power/                # Power 模块代码，此路径下可以link Docs下文档
│   └── BSW/                # BSW 模块代码，此路径下可以link Docs下文档
├── tests/                  # [Test] 测试代码
├── docs/                   # [Docs] 文档目录 (与 src 同级)
│   ├── index.md            # 文档门户入口
│   │
│   ├── 01_requirements/    # [原 RD 阶段] 系统级需求 (SRS)
│   │   ├── system_req.md   # 整车/系统需求
│   │   └── safety_req.md   # 功能安全需求 (FSR)
│   │
│   ├── 02_architecture/    # [原 SD 阶段] 系统级架构与接口
│   │   ├── system_design.md        # 系统顶层设计
│   │   └── communication_matrix.md # 通信矩阵 (CAN/LIN)
│   │
│   └── 03_modules/         # [原 MD 阶段] 模块级设计 -> 垂直聚合所有资料
│       ├── Power/            # Power 模块 (包含该模块的 RD/SD/MD)
│       │   ├── design.md           # 详细设计 (原理/状态机)
│       │   ├── api_interface.md    # 接口定义 (RTE/IO)
│       │   └── test_plan.md        # 单元测试计划
│       └── BSW/
│           ├── design.md 
│           └── ...
└── README.md

Git 工作流示意（Mermaid 演示）：
main feature-Power_change Ver0.85 Code: Power代码变更提交 Docs:Power文档设计变更提交 Merge: Code+Doc Release Ver0.9

图注：在 feature-Power_change 分支中，代码修改与文档更新（高亮部分）在同一个合并请求（Merge Request）中完成，可以要求review者对此有审查要求或者结合CI设置门禁进行管理，确保发布时二者一致。

4.3 标准化表格的清晰呈现 (Structured Tables)

Markdown 原生表格语法非常适合处理车载软件开发中的标准技术数据。而且Excel表格可以直接复制到Typora等md编辑器中直接编程md格式内容，Markdown 表格具有天然的规范性。

示例：CAN 信号接口定义表

Signal Name	Start Bit	Length	Factor	Offset	Unit	Receiver
VehSpd	0	12	0.1	0	km/h	VCU, IVI
EngSpd	12	14	0.5	0	rpm	VCU, TCU
BattVolt	26	8	0.2	0	V	BMS
GearPos	34	4	1	0	-	ICU

图注：上表即为 Markdown 源码渲染效果，清晰、轻量，且 AI 极其容易提取其中的键值对。

4.4 工程图表的代码化与多样性 (Diagrams as Code)

针对车载开发对逻辑可视化的强需求，由于markdown文本天然支持Mermaid语法，我们将利用 Mermaid 或 PlantUML 实现"图表即代码"。这允许我们直接在文档中"编写"图表，而非粘贴图片。对于这种代码性的语言，AI也更容易识别并转换成工程设计代码。对于mermaid语法非常直观简单，具体参照：

流程图表语法 | Mermaid 中文网

我们也可以看到他可以生成多种形式图，我们常用的图基本都可以使用代码绘制。
Mermaid

图表体系
逻辑与架构
Flowchart流程图
State状态图
Class类图
C4图
交互与时序
Sequence时序图
Journey用户旅程
项目与管理
Gantt甘特图
GitGraphGit图
Req需求图
可视化
Mindmap思维导图
Pie饼图
Timeline时间轴

语法的学习成本较低，同时结合AI，我们也可以先手绘图形，然后让AI生成mermaid语法，或者本身直接通过自然聊天语言生成mermaid语法。

下面内容是对于几种常用图的示例：

示例 1：ECU 交互时序图 (Sequence Diagram)
HMI MCU VCU BMS HMI MCU VCU BMS 监测电池状态 par [并行处理] 发送 SoC=15% (低电量警报) 判定进入功率限制模式 (Limp Home) 发送扭矩限制指令 (MaxTrq=50Nm) 响应限制确认 请求显示"动力受限"图标 (可选) 驾驶员确认

示例 2：控制逻辑状态机 (State Diagram)
满足开启条件
驾驶员踩刹车
驾驶员按 Resume
传感器故障
系统重置
Standby
Active
Override
Fault

示例 3：架构块图 (Block Diagram)
Basic Software (基础软件层)
Application Layer (应用软件层)
Microcontroller Abstraction Layer
ECU Abstraction Layer
Services Layer
SWC: Sensor Fusion
SWC: Motor Control
RTE (Runtime Environment)
OS / System Services
Com Services
IO Hardware Abstraction
MCU Driver
ADC Driver
CAN Driver
Microcontroller (Hardware)

示例 4：详细设计类图 (Class Diagram)

用于描述 C++ 模块的类结构与继承关系，适合详细设计 (DD) 阶段。
implements
uses
composition
PowerManager
-currentMode : PowerState
+init()
+requestMode(mode : PowerState)
+process()
<<Interface>>
BatterySensor
+getVoltage() : : float
+getCurrent() : : float
HighVoltageBattery
+getSoC() : : float
+isOverTemp() : : bool
SafetyMonitor
+checkLimits()
+reportFault(code : int)

示例 5：甘特图 (Gantt甘特图)

用于描述任务计划流程
2026-01-04 2026-01-11 2026-01-18 2026-01-25 2026-02-01 2026-02-08 2026-02-15 A task Task in Another another task Another task Section Another Power设计

4.5 自动化构建与检查 (CI/CD Pipeline)

引入静态网站生成器（如 MkDocs, Hugo），在流水线中自动将 Markdown 编译为便于阅读的 HTML 网页，并进行格式校验。

文档构建流水线示意图：
CI/CD Server
Pass
Pass
Success
Fail
Git Push
Pipeline Trigger
Check Markdown Syntax
Check Broken Links
Build Static HTML
Deploy to Doc Server
Email Alert

4.6 高效的在线审查与发布流程 (Streamlined Review Workflow)

结合 Git 平台与 CI 构建产物，我们重构了文档的审查流程，使其不再依赖于文件的物理传输，充分释放 Docs-as-Code 的协作效能。

• Diff 视图审查 (For Reviewer)： Reviewer 不再需要下载 Word 文档并开启"修订模式"，而是直接在 GitLab/Gerrit 的 Merge Request 页面，通过 Diff 视图查看文档变更。这使得"代码实现"与"文档设计"的差异在同一个界面中一目了然，支持针对具体行的 Inline Comment（行内评论）。

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

• 在线预览验收 (For SQA/PM)： SQA 无需拉取代码仓库。通过 CI 流水线，每次提交都会自动构建一个临时的 HTML 预览版本。SQA 仅需点击 Pipeline 中的 artifact 链接，即可在浏览器中查看渲染后的最终文档，进行格式规范性检查和内容验收。

• 自动化合规脚本 (Automated Compliance)： 针对 ASPICE（SQA审查） 等合规要求，集成 Python 脚本在 CI 阶段运行，自动扫描 Markdown 元数据，验证 Trace ID 的完整性、检查死链以及术语表的一致性，输出合规性报告，辅助 SQA 快速放行。

5. 结果 (Results)

5.1 核心成果指标 (Key Outcomes)

基于初步验证与行业案例分析，转型后预计达成以下结果：

1. AI 解析准确率提升：相比 Word 文档，LLM 对 Markdown 格式技术文档的 RAG（检索增强生成）检索准确率预计显著提升，Token 利用率提高，因为去除了大量无效的格式噪音。
2. 文档维护成本降低：利用 Git Diff 功能，评审者仅需关注变更行，文档 Review 时间缩短。
3. 一致性保障：通过 CI 门禁，强制要求代码与文档同步提交，彻底解决文档滞后问题，实现 100% 的版本对齐。

5.2 基于 V 模型的全链路效能提升预测 (V-Model Efficiency Forecast)

采用 Docs-as-Code 模式后，文档不再是静态的归档物，而是贯穿 V 模型全生命周期的活跃资产。我们在以下关键环节预测将获得显著收益：

V 模型阶段	关键环节	质量提升 (Quality)	预测速度提升 (Speed)
需求/架构	协同编写	消除版本冲突：Git 自动合并机制避免了"谁覆盖了谁的文档"事故，确保多人协作的数据完整性。	编写效率 ↑：工程师专注于逻辑而非成果物排版；Mermaid 代码绘图初次设计结合AI进行绘制，标准性统一，后续小范围更改可直接修改mermaid代码
详细设计	同行评审	精准 Diff：评审聚焦于实质性的逻辑变更，而非格式差异，漏看率大幅降低。	评审周期 ↓：异步在线评审替代了冗长的线下会议；Review 耗时预计减少 40%。
软件实现	代码对齐	逻辑一致性：文档与代码在同一 IDE、同一 Commit 中修改，彻底杜绝"两张皮"现象。	上下文切换 ↓：无需在 Office和 IDE 间频繁切换，开发体验更流畅，后续引入AI vibe code开发，前序md成果物可直接成为input资料提供给AI，加速代码输出精度和速度
测试验证	追溯分析	合规自动化：脚本自动保障 Trace ID 完整性，人为疏漏导致的断链风	验收效率 ↑：SQA 可直接查看自动生成的 HTML 和合规报告，无需人工抽检格式。

6. 考察 (Discussion)

在推行过程中，我们识别出以下需要重点应对的挑战与考量点：

6.1 车载行业标准的合规性 (ASPICE/ISO 26262)

虽然 Markdown 提升了效率，但 ASPICE 等标准要求严格的双向追溯性（Requirements <-> Architecture <-> Design <-> Code <-> Test）。

• 分析：纯文本缺乏传统 Office 工具的 ID 强绑定功能，若无辅助手段，容易在人工编辑过程中出现断链。

• 对策：

  1. 元数据定义与行内标记：

     • 文件级元数据：使用 YAML Front Matter 定义模块属性。
     • 需求级标记：在正文中使用特定的标题格式或注释标记来定义具体需求 ID，实现"单文件多需求"。

     示例：模块化设计文档源码（单文件包含多条需求）

     ---
     # [文件级属性]
     module: "VCU_Torque_Control"
     author: "Zhang San"
     label: "Request list"
     ---
     
     # 1. 扭矩控制模块设计
     
     ## 1.1 加速踏板解析
     <!-- {REQ_ID: SRS_VCU_001} {Trace: SYS_PT_005} -->
     ### [SRS_VCU_001] 踏板Map映射
     VCU 应接收踏板位置信号 (0-100%)，并通过查表 (Map_Pedal_Torque) 输出原始请求扭矩。
     
     ## 1.2 扭矩限制
     <!-- {REQ_ID: SRS_VCU_002} {Trace: SYS_PT_008} -->
     ### [SRS_VCU_002] 过热保护限制
     当电机温度超过 `Thresh_Temp_High` 时，输出扭矩应限制在 50% 以内。

     *说明：通过在标题中包含 ID（如 [SRS_VCU_001]）或使用 HTML 注释 <!-- ... --> 埋点，脚本工具可以扫描单一文件解析出多条需求，既保留了文档的连贯性，又满足了追溯要求。*这些属性要求是方便CICD或者相关脚本汇总核心数据使用。

     对于有元数据的内容，CICD使用YAML更加方便识别：

     

  2. 可视化辅助 ：利用 Todo Tree 等 VS Code 插件，通过正则表达式（如匹配 REQ-123）在编辑器侧边栏实时展示需求 ID 在代码和文档中的引用位置，实现轻量级的可视化追溯。
     

  3. 自动化验证：编写脚本扫描和验证追踪链的完整性，确保无悬空需求。

6.2 信号矩阵处理的局限性

车载软件严重依赖 CAN/LIN 矩阵和标定参数表。Markdown 原生表格不支持复杂操作。

• 分析：虽然 Markdown 对标准表格支持很好（如 4.3 节所述），但对于数千行的复杂信号矩阵，强行用 Markdown 画大表仍然效率较低。
• 对策：确立"数据与文档分离"原则。复杂的信号定义保留在 CSV/Excel 中，作为工程输入文件；Markdown 文档只负责描述逻辑和引用数据文件。

6.3 团队技能转型

• 分析：非研发人员可能不习惯使用 IDE 或 Git。
• 对策：初期引入 Typora 等所见即所得编辑器作为过渡；中长期可部署基于 Git 的 CMS 系统（如 Wiki 形式），后端自动同步为 Markdown。

7. 结论 (Conclusion)

综上所述，将车载软件开发文档转换为 Markdown 格式并在 Git 体系下管理，在技术上是完全可行的，且战略意义重大。

该转型不仅符合"文档即代码"的先进工程理念，更是公司后续引入 AI 辅助编程、构建企业级研发知识库的必要前置条件。

建议推进路线：

1. 短期：选取非功能安全相关的应用层模块进行试点，跑通 Git+Markdown 流程。
2. 中期：搭建自动化文档构建平台，解决预览和搜索问题。
3. 长期：开发 AI 助手，基于 Markdown 文档库实现自动化的代码审查和需求分析。