Magna-Power 的文档工程化实践
所有在产产品共用一套文档代码库，命令参考由固件自动生成，手册可同时以 HTML、PDF 和面向 AI 工具的 Markdown 格式发布。
Magna-Power 在十个产品系列中提供超过 300,000 个 SKU。如此丰富的产品阵容源于周密的长期规划，以及针对通用编程接口和可配置组件所做的刻意工程设计。xGen 平台使用同一套固件代码库，覆盖 MagnaDC 电源 SLx 系列、MagnaLOAD 直流电子负载 ALx 系列、阻断二极管附加模块 BDx 模块以及高稳定性附加模块 DBx 模块，并在所有产品中采用同一套 SCPI 命令集和相同的通信接口选项。MagnaDC 电源的 SL、XR、TS、MT 和 ML 系列同样共用相同的固件和功能，各系列之间的选件也保持一致。从一个系列切换到另一个系列时，安装和编程章节所描述的大部分功能都是相同的。
共享的工程设计理应带来共享的文档，但很长一段时间内并非如此。每个系列都有各自独立维护的手册。对共享接口的任何变更，都必须复制到所有提及该接口的手册中，从而导致内容出现偏差。某一本手册得到了修正，其他手册则难免遗漏。
Magna-Power 持续改进的企业文化让这一情况更加棘手。去年，xGen 开发团队在七个软件版本中产出了近 200 个功能与缺陷修复工单，每一项客户可见的变更都必须在同一版本中准确无误地落实到相应的手册里。依赖人工发现每项变更并手动编辑多份文档的流程无法扩展。一旦进度落后，最先发现问题的就是客户。
因此，我们把文档重建为一套工程系统：单一代码库、共享组件、自动化构建、版本化发布，以及直接由固件生成的命令参考。本月发布的 Snapshot 75 已将所有在产产品手册纳入这套系统。
单一来源，所有产品共享
每个产品系列都有各自的文档项目，每个项目都会引入多个以 Git 子模块形式固定版本的共享组件：构建配置与工具链、网页 HTML 主题，以及适用于其产品系列和产品世代的通用内容库。
共享内容库的设计目的是避免重复。例如，水冷章节过去存放在 TS 系列手册中，其他手册里则是经过修改的副本。现在它只存在一份，TS、SL 和 ML 系列手册都会引用它。系列特有的细节，例如 ML 系列的冷却液旁路接口，也位于同一页面，并且仅出现在适用的手册中。对通用内容的修正会在下一次构建时同步到全部三本手册。
Magna-Power 团队还决定采用严格构建：警告即视为错误，因此失效的交叉引用或缺失的插图会直接中止发布，而不会以死链接的形式交付。这一限制确保共享内容的修改不会悄无声息地破坏同系列的其他手册。
由固件生成的命令文档
每条 SCPI 命令都在固件源代码中以结构化数据的形式定义：语法、参数及其范围、查询形式、说明和示例。固件构建根据该表生成命令解析器，文档构建则根据同一张表生成编程章节。
文档生成器了解自己正在为哪个产品系列构建文档。例如，电源有启用其直流输出的命令，而电子负载则有启用其直流输入的命令。同一套定义可为每种产品类型生成正确的参考内容，仅列出该产品实际支持的命令。
其回报体现在响应速度上。工程师为某条命令添加参数时，只需编辑一处定义。下一次固件构建即可接受该参数，文档构建则会使用工程师自己撰写的说明和示例对其进行描述。这种基于固件的文档成为代码评审流程的一部分，既保证了正确性，也无需向第三方移交。
通过持续集成工作流构建与发布
该构建流程运行在我们自有的持续集成服务器上，这台服务器同时负责编译固件、MagnaCTRL 软件以及测试和校准工具。文档与其他构建产物一样：带有自己的版本标签，并与其所描述的固件一起打包进同一个发布快照。本月发布的 Snapshot 75 将固件 0.084 与带有版本标签的 SLx、ALx、BDx 和 DBx 手册配套发布。
一次构建即可从同一份源文件生成三种输出：用于网页手册的 HTML；通过 LaTeX 排版的 PDF，供客户打印并随项目归档；以及面向大语言模型的 Markdown。一套共享的 LaTeX 版式统一规范了每本手册的排版、带编号的图表以及交叉引用，细致到将尺寸图缩放至适合页面，并避免命令名称在换行处被断字。
网页版手册
网页版手册还采用了全新的自研主题，其设计与 magna-power.com 保持一致。技术图纸均为矢量图形，点击后可在灯箱中按合适比例缩放显示，无需下载 PDF。代码示例带有语法高亮和复制按钮。左侧导航会随滚动实时跟踪您的阅读位置。深色模式会反转线条图，使黑色透明底的图纸依然清晰可读，而徽标和照片则保持不变。警告和注意提示框在两种模式下均采用标准配色的 ISO 7010 安全警示符号。字体为自托管，确保手册保存为离线版本时外观依然一致。
文档版本切换器
此前，网上只提供产品手册的最新版本，旧版本会被覆盖。如果您基于较早的固件调试了系统，并希望查阅当时对应的手册，就很难（轻松地）获取到。
现在，每本手册都带有文档版本切换器。最新版本仍位于产品的常规地址，所有早期版本均已归档。每次构建时，持续集成服务器都会在产品文档根目录写入一份版本清单，切换器在页面加载时读取该清单。因此，归档页面会列出自其发布以来所有已发布的版本，包括较新的版本。选择某个版本后，如果该版本中存在相同页面，则会跳转到该页面；如果不存在，则跳转到该版本的首页。归档页面带有横幅提示，说明您正在阅读的版本，并附有指向最新版本的链接。
文档版本的编号独立于固件，二者通过发布快照进行配对。归档从本次发布开始，因此更早的构建版本可能无法获取。
可直接交给 AI 助手的手册
越来越多的工程师将手册交给 AI 助手，请它编写测试脚本或解读状态寄存器。PDF 文本提取可能会打乱阅读顺序和表格结构，如下例所示，该示例使用常见的 Python 库 pdftotext 转换了 PDF 中的一页。
现在，每本手册还会按照 llms.txt 约定以纯文本形式发布：在手册根目录提供一份索引，在每个 HTML 页面旁提供对应的 Markdown 版本，并提供一个包含整本手册的合并文件。Markdown 格式可确保标题、表格和代码块保持完整。危险提示现在以带标签的区块呈现，因此 AI 助手在总结安装步骤时，看到的警告与人工阅读时完全一致。这些文本文件与 HTML 出自同一次构建，因此始终保持同步。如果该步骤失败，整个构建也会随之失败，而不会部署缺少这些文件的手册。
将文档视为产品的一部分，使我们能够把每一项改进落实到所有需要它的手册中，并与其所说明的功能同步发布。客户可以获得针对其设备的一致指导，并以最能支持其工作的版本和格式使用这些内容。
以下是 SLx 系列的参考文档示例，均由同一份源文件构建：