Serial Studio 文档评审标准详解manual-heuristics 十条手册启发式的 0–4 评分量表【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-Studio在 Serial Studio 仓库中doc/help/下的用户手册并不是写完就算而是被一套多层次的评审流水线把关词法级 linter、结构级二阶 AI 写作痕迹检查、事实核查factcheck之外还有一个专门的手册启发式量表manual heuristics rubric。本文以 .claude/skills/ss-docs/references/manual-heuristics.md 为主体完整解读这份 0–4 序数量表的评分语义、十条启发式的判定细则与报告格式并结合仓库中的 ss-docs 技能定义、事实核查规程、help.json 导航图 与 文档 linter 脚本 说明它在整个文档质量门禁中的位置与实操用法。读完后你可以独立地对任意一篇 doc/help 页面做 0–4 分评分产出带 P0–P3 严重级别标签的评审报告并与 factcheck 结论交叉验证。量表定位ss-docs 评审工作流中的第四道门manual-heuristics 量表本身不开创新规则它捕获的是前两道门都漏掉的那一类问题——原文开篇就点明了这一点a phrase-clean, structurally-varied page that still documents the wrong default措辞干净、结构多样的页面但写错了一个默认值。从 ss-docs SKILL.md 的 Review workflow 可以看到完整的分层评审顺序第一阶运行python scripts/documentation-verify.py scope总结词法级发现营销词汇、教程口吻、meta 指称、破折号滥用等不手工重复其结论第二阶按 second-order-tells.md 做结构级检查对冲词堆叠、三段式节奏、对称列表膨胀等 14 类经词汇修正后仍存活的 AI 痕迹每处命中给出 file:line 和引文事实核查抽取页面中所有可验证的断言对照core/、app/src、app/qml源码逐条给出 VERIFIED / WRONG / NOT FOUND 判定规程见 ground-truth-factcheck.md启发式量表按本文讲解的十条启发式给页面打 0–4 分发现项打 P0–P3 标签E-E-A-T 检查trust 优先事实核查判定、版本门控披露、范围诚实再评估 experience/expertise/authority见 eeat-manual.md输出 P0 → P3 优先级报告。任何 WRONG 事实断言一律 P0且评审是只读的——Never silently fix。这个分层设计背后的逻辑是documentation-verify.py 是词法过滤器绝大多数 AI 生成的散文能轻松通过它二阶结构检查过滤掉通过词法过滤后仍读起来像 AI的模式而启发式量表则回答一个更高层次的问题——即使语言与结构都无可挑剔这篇页面是否还在正确地记录软件的实际行为以及读者能否冷启动进入、按需退出。评分尺度与严重级别映射量表的每条启发式独立打 0–4 分每个分数对应一个严重级别severity tag分数含义严重级别0缺失或主动错误Absent or actively wrongP0 — 阻塞性错误事实、误导性页面1重大缺口Major gapsP1 — 交接前必须修复2好坏参半MixedP2 — 尽快修复3良好仅有小缺口Good, minor gapsP3 — 打磨项4优秀Excellent罕见无两条硬规则保证量表不会被平均分稀释任何一条 0 分或 1 分报告里就至少产生一个 P0/P1 发现项一条错误的 ground-truth 断言WRONG无论其余九条得分多高本身就是 P0。第二条规则把量表与事实核查强耦合启发式 5见下文的打分必须建立在 factcheck 实际运行过的前提上而不是凭印象给分。十条手册启发式逐条解读1. 意图可见性Visibility of intent首段必须说清三件事这个功能是什么、它是 Pro 功能还是免费功能、它在 UI 中的位置在哪里。读者应当在五秒内知道这个页面能否回答自己的问题。这条对应 ss-docs 新条目清单中的页面形状约定# Titlesentence case## Overview先行Overview 里陈述功能与版本门控Pro or free。Pro gating stated late版本门控交代太晚正是量表报告格式示例中出现的真实 P3 发现项。在 Serial Studio 仓库中门控声明的可验证锚点是SerialStudio::activated()/commercialCfg()调用点——ground-truth-factcheck.md 将Requires a Pro license这类断言归为 edition gating 类ground truth 就是保护该功能的调用点而 Pro-vs-Free.md 页面则是门控信息的集中登记处。2. 标题-内容匹配Heading-content match标题是一份合同该节必须在开头 100 词内兑现标题暗示的内容顺序也要符合标题暗示的次序。不允许诱饵标题bait-and-switch不允许把承诺的内容埋在后文。这条规则针对的是结构层面的违约与二阶检查中的Question-cadence headingsFAQ 之外标题应为名词短语互补后者管标题的语法形态本条管标题与正文的语义契约。从 doc/help/help.json 可见 Serial Studio 手册的标题普遍是名词短语Drivers-Modbus、Session-Database而 help.json 中的title字段如 Frame Parser Reference就是各页标题-内容合同的导航侧登记。3. 读者控制与退出Reader control and exit三条具体要求小节自包含读者可以冷启动进入任意小节不依赖未命名页面的上下文相关链接出现在读者需要的地方而不是只堆在页脚页面位于正确的 help.json 分区保证导航能把它找到。第三条直接指向 doc/help/help.json 的图结构。该文件是手册的导航注册表每个条目含id、title、section、file四字段页面按section分桶——Basics、Configuration、Scripting Data Logic、Connectivity、Drivers、Data Management、Integration、Architecture、Support、Licensing。一个 UART 驱动页面若被登记进 Configuration 分区导航语义就错了ground-truth-factcheck.md 把交叉引用归为可核查断言[UART](https://link.gitcode.com/i/cdf100bec94a28b9f462ef5fff2c461d)这类链接要求目标文件存在且条目已注册进 help.json。4. 术语一致性Terminology consistencyUI 字符串就是术语全文统一使用并与 Glossary.md 对齐。原文给出的反例一针见血不允许为了行文变化而在 frame parser / parser script / JS parser 之间轮换称呼也不允许偏离应用实际显示的文本。ss-docs 技能的 Rules 一节将此上升为全局不变量Keep the manuals terminology stable: the UI string is the term (Project Editor, frame parser, Setup panel) — no synonym rotation for variety. 这条启发式的落地方式是可操作的对任意术语先 grepapp/qml/**里的 UI 字符串确认应用实际显示什么再以该字符串作为手册术语。help.json 中 id 为javascript-api的条目标题即 Frame Parser Reference文件 JavaScript-API.md可见frame parser是贯穿手册与导航的统一术语。5. ground-truth 预防Ground-truth prevention这是十条中最重的一条也是量表与事实核查的交汇点每一个默认值、取值范围、UI 标签、快捷键、文件格式和门控断言都必须能对照core//app/src/app/qml验证——并且确实验证过原文直接引用了 ground-truth-factcheck.md 作为程序依据。量表给出了两个锚定判定写the app handles this automatically却不说明它实际做了什么得 1 分写错一个默认值得 0 分。factcheck 规程为这条启发式提供了操作化定义断言按kind分类默认值、范围/选项、UI 标签/菜单路径、版本门控、行为、文件/格式、CLI flag、交叉引用每类都指明 ground truth 在哪里——例如Data bits: 5, 6, 7, 8的 ground truth 是喂给 UI 的枚举、下拉框模型或校验器Reconnects automatically on disconnect的 ground truth 是实现该行为的 slot/handler。判定只有三种VERIFIED附file:line、WRONG附file:line 正确事实、NOT FOUND列出尝试过的搜索交给维护者不许猜。量表报告示例中的 P0 案例——Baud default documented as 115200; code says 9600——正是这条启发式失守的典型形态。6. 识别优先于回忆Recognition over recall读者跟随本页时永远不需要某个未命名页面的上下文行话要么就地定义要么链接到 Glossary.md前置条件要么点名要么给链接比较类内容用表格不埋在散文里。这条对应 E-E-A-T 翻译里的 Expertise 信号协议术语按行业用法使用parity、QoS、PGN并与 Glossary 一致。与启发式 3 的区别在于视角3 管读者能否自由进出页面6 管读者是否需要背诵未给出的上下文。7. 快读者与深读者的弹性Skimmer vs deep-reader flexibility阅读模式与内容形态必须匹配配置参数放表格、操作步骤用编号列表、原理用散文。快读者应该能不读原理部分就提取到他需要的那个参数。这是 Serial Studio 手册的标准页面形状ss-docs 新条目清单原话configuration tables, numbered quick starts, platform notes where behavior differs也是二阶检查中Uniform section shape反面的正面要求——真实的手册章节应当变化从 help.json 的 Drivers 分区规模可以看出UART、Modbus、OPC UA 各占一整页且形态各异而某些简单功能可能只需要一段话二阶检查原文即举此例UART needs a page, Process I/O needs a paragraph。8. 信息密度Information density每个段落都要挣得它的位置四条禁令首个实质断言之前不许有热身式开头throat-clearing intro不许有复述该节内容的总结段不许为让薄功能显得有深度而注水页面长度必须匹配功能范围。这一条与 second-order-tells.md 中的Wrap-up questions and summary paragraphs检查互为表里后者是结构级的检测手段In summary...段、What does this mean for you?式收尾本条是评分级的价值判断。9. 失败恢复Failure recovery页面必须预判那些设置跑不通的读者行为随平台差异的地方给平台注记常见故障给症状 成因更深层次的诊断在 Troubleshooting.md 里的就给链接。eeat-manual.md 把Platform caveats: Where behavior differs by OS, the page says so and says how列为 Trust 信号之一——平台差异不只是要提还要说清楚怎么个不同法例如 factcheck 规程中把port name examples的 ground truth 定位到平台相关字面量COM3、/dev/ttyUSB0这类值在代码里可查。10. 嵌入手册图Embedded in the manual graph页面必须是手册图manual graph的正式成员四个条件注册进 help.jsonid、title、section、file四字段齐全交叉链接双向运行本页链接它的亲戚页至少一个现有页面链接回来它引入的术语存在于 Glossary.md——若手册别处没有定义这些术语新条目要负责补进 Glossary不存在孤儿页面。ss-docs 技能的更新工作流将此写成硬性检查项New pages register indoc/help/help.json… and cross-link in both directions — the page links its relatives, and at least one existing page links back. 至少一个现有页面链回这一要求是 Serial Studio 特有的图完整性约束比通常的单向交叉引用更严格它保证从任意亲戚页都能走回新页面导航没有死胡同。评审报告格式量表规定了一份固定报告模板每条启发式一行含分数、严重级别与备注## Manual heuristics: page | # | Heuristic | Score | Severity | Note | |---|-----------|-------|----------|------| | 1 | Visibility of intent | 3 | P3 | Pro gating stated late | | 5 | Ground-truth prevention | 0 | P0 | Baud default documented as 115200; code says 9600 | | ... | ... | ... | ... | ... | ### Prioritized fixes - P0: ... - P1: ... - P2: ... - P3: ...使用时的要点表头page替换为被评审页面Note 列给出一句话证据性描述如示例中直接写出文档说 115200代码是 9600这种可追溯的事实落差Prioritized fixes 严格按 P0 → P3 排序与 ss-docs 评审工作流第 6 步Report prioritized P0 → P3对齐报告是只读产物评审模式下report — do not fix unless asked不允许静默修改文档。交叉验证规则量表与 factcheck 互锁量表末尾有一条自我审计规则原文为Cross-check against the factcheck verdicts: a page scoring 3 across the board while carrying a WRONG claim means heuristic 5 was scored without running the factcheck — run it.翻译成人话一个整体得分 3 的页面却背负着 WRONG 断言说明启发式 5 是在没有跑 factcheck 的情况下打的分——回去跑一遍。这条规则把量表变成一个可自证的系统factcheck 的判定喂给启发式 5 的分数反过来分数与判定的矛盾又暴露评分过程本身被跳过。它与 eeat-manual.md 的评分流一致——Trust 先行Trust: any WRONG claim, undisclosed gating, or oversold capability → page fails, stop其余信号随后评分。谱系从 Nielsen 十大可用性启发式到手册量表manual-heuristics 不是凭空设计的原文开篇交代了完整的改编链源头Nielsen 的 10 Usability HeuristicsNN/g1994 年2020 修订版——可用性工程的经典框架第一站claude-blog 项目的editorial-heuristics.mdMIT 许可把可用性启发式转译为博客编辑质量检查第二站经 impeccable 插件Apache 2.0的方法论传导再经 ss-docs SKILL.md 所述rescoped from SEO-blog writing to a technical manual替换内容博客侧的关切SEO 元数据、作者传记、E-E-A-T、FAQ schema被手册侧的关切取代——ground truth代码事实、edition gatingPro/Free 门控、help.json 导航图。值得注意的一个细节SKILL.md 说E-E-A-T survives the translation——它没有被丢弃而是以 eeat-manual.md 的形式转译为手册形态无署名、以具体性体现经验、以诚实范围体现可信度并作为评审工作流的独立一道门与启发式量表并行运行。量表负责结构与契约E-E-A-T 负责信任与深度factcheck 负责事实三者共同构成 ss-docs 评审的完整判据集。实操要点如何对一篇 doc/help 页面执行量表评审结合上述规则与 ss-docs 评审工作流对任意一篇手册页面的完整评审流程是先跑 linterpython scripts/documentation-verify.py doc/help/Page.md把词法级发现原样汇总不手工重复该脚本跳过代码围栏、行内代码、链接 URL 与 HTML 注释发现按 kind 分组如ai-marketing-phrase、ai-tutorial-voice、style-emdash-density等再跑二阶结构检查linter 干净后才进行按 second-order-tells.md 逐条报告命中抽取断言做 factcheck对每个可验证断言 grep 源码先精确匹配用户可见字符串再匹配符号给出 VERIFIED / WRONG / NOT FOUND 与file:line证据tests/ 可以佐证行为断言但永不替代实现代码作为 ground truth逐条打 0–4 分十条启发式独立评分其中第 5 条必须直接引用第 3 步的判定按 P0 → P3 排序输出修复清单WRONG 断言无条件 P0最后交叉验证检查分数与 factcheck 判定是否自洽不自洽则说明某一步被跳过重跑对应环节。一个实用的判断基准来自 eeat-manual.md 对 Experience 的最低要求一个没有可粘贴示例、没有具体数值、没有边界案例的页面等于用散文写的 UI 截图a UI screenshot in prose属 P1。这为量表第 7、8 两条阅读模式匹配、信息密度提供了可操作的及格线。小结manual-heuristics 量表的价值在于把这篇手册写得好不好这个主观判断压缩为十条可独立打分、可映射严重级别、可与事实核查互锁的客观判据。它与 ground-truth-factcheck.md事实、second-order-tells.md结构、eeat-manual.md信任共同构成 Serial Studio 文档质量的完整评审框架而 scripts/documentation-verify.py 与 doc/help/help.json 则分别提供了词法自动化检查与手册图注册的仓库侧锚点。对维护者而言这套量表既是新页面的写作自查清单也是评审他人提交时的统一裁判标准。【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-Studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Serial Studio 文档评审标准详解：manual-heuristics 十条手册启发式的 0–4 评分量表
Serial Studio 文档评审标准详解manual-heuristics 十条手册启发式的 0–4 评分量表【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-Studio在 Serial Studio 仓库中doc/help/下的用户手册并不是写完就算而是被一套多层次的评审流水线把关词法级 linter、结构级二阶 AI 写作痕迹检查、事实核查factcheck之外还有一个专门的手册启发式量表manual heuristics rubric。本文以 .claude/skills/ss-docs/references/manual-heuristics.md 为主体完整解读这份 0–4 序数量表的评分语义、十条启发式的判定细则与报告格式并结合仓库中的 ss-docs 技能定义、事实核查规程、help.json 导航图 与 文档 linter 脚本 说明它在整个文档质量门禁中的位置与实操用法。读完后你可以独立地对任意一篇 doc/help 页面做 0–4 分评分产出带 P0–P3 严重级别标签的评审报告并与 factcheck 结论交叉验证。量表定位ss-docs 评审工作流中的第四道门manual-heuristics 量表本身不开创新规则它捕获的是前两道门都漏掉的那一类问题——原文开篇就点明了这一点a phrase-clean, structurally-varied page that still documents the wrong default措辞干净、结构多样的页面但写错了一个默认值。从 ss-docs SKILL.md 的 Review workflow 可以看到完整的分层评审顺序第一阶运行python scripts/documentation-verify.py scope总结词法级发现营销词汇、教程口吻、meta 指称、破折号滥用等不手工重复其结论第二阶按 second-order-tells.md 做结构级检查对冲词堆叠、三段式节奏、对称列表膨胀等 14 类经词汇修正后仍存活的 AI 痕迹每处命中给出 file:line 和引文事实核查抽取页面中所有可验证的断言对照core/、app/src、app/qml源码逐条给出 VERIFIED / WRONG / NOT FOUND 判定规程见 ground-truth-factcheck.md启发式量表按本文讲解的十条启发式给页面打 0–4 分发现项打 P0–P3 标签E-E-A-T 检查trust 优先事实核查判定、版本门控披露、范围诚实再评估 experience/expertise/authority见 eeat-manual.md输出 P0 → P3 优先级报告。任何 WRONG 事实断言一律 P0且评审是只读的——Never silently fix。这个分层设计背后的逻辑是documentation-verify.py 是词法过滤器绝大多数 AI 生成的散文能轻松通过它二阶结构检查过滤掉通过词法过滤后仍读起来像 AI的模式而启发式量表则回答一个更高层次的问题——即使语言与结构都无可挑剔这篇页面是否还在正确地记录软件的实际行为以及读者能否冷启动进入、按需退出。评分尺度与严重级别映射量表的每条启发式独立打 0–4 分每个分数对应一个严重级别severity tag分数含义严重级别0缺失或主动错误Absent or actively wrongP0 — 阻塞性错误事实、误导性页面1重大缺口Major gapsP1 — 交接前必须修复2好坏参半MixedP2 — 尽快修复3良好仅有小缺口Good, minor gapsP3 — 打磨项4优秀Excellent罕见无两条硬规则保证量表不会被平均分稀释任何一条 0 分或 1 分报告里就至少产生一个 P0/P1 发现项一条错误的 ground-truth 断言WRONG无论其余九条得分多高本身就是 P0。第二条规则把量表与事实核查强耦合启发式 5见下文的打分必须建立在 factcheck 实际运行过的前提上而不是凭印象给分。十条手册启发式逐条解读1. 意图可见性Visibility of intent首段必须说清三件事这个功能是什么、它是 Pro 功能还是免费功能、它在 UI 中的位置在哪里。读者应当在五秒内知道这个页面能否回答自己的问题。这条对应 ss-docs 新条目清单中的页面形状约定# Titlesentence case## Overview先行Overview 里陈述功能与版本门控Pro or free。Pro gating stated late版本门控交代太晚正是量表报告格式示例中出现的真实 P3 发现项。在 Serial Studio 仓库中门控声明的可验证锚点是SerialStudio::activated()/commercialCfg()调用点——ground-truth-factcheck.md 将Requires a Pro license这类断言归为 edition gating 类ground truth 就是保护该功能的调用点而 Pro-vs-Free.md 页面则是门控信息的集中登记处。2. 标题-内容匹配Heading-content match标题是一份合同该节必须在开头 100 词内兑现标题暗示的内容顺序也要符合标题暗示的次序。不允许诱饵标题bait-and-switch不允许把承诺的内容埋在后文。这条规则针对的是结构层面的违约与二阶检查中的Question-cadence headingsFAQ 之外标题应为名词短语互补后者管标题的语法形态本条管标题与正文的语义契约。从 doc/help/help.json 可见 Serial Studio 手册的标题普遍是名词短语Drivers-Modbus、Session-Database而 help.json 中的title字段如 Frame Parser Reference就是各页标题-内容合同的导航侧登记。3. 读者控制与退出Reader control and exit三条具体要求小节自包含读者可以冷启动进入任意小节不依赖未命名页面的上下文相关链接出现在读者需要的地方而不是只堆在页脚页面位于正确的 help.json 分区保证导航能把它找到。第三条直接指向 doc/help/help.json 的图结构。该文件是手册的导航注册表每个条目含id、title、section、file四字段页面按section分桶——Basics、Configuration、Scripting Data Logic、Connectivity、Drivers、Data Management、Integration、Architecture、Support、Licensing。一个 UART 驱动页面若被登记进 Configuration 分区导航语义就错了ground-truth-factcheck.md 把交叉引用归为可核查断言[UART](https://link.gitcode.com/i/cdf100bec94a28b9f462ef5fff2c461d)这类链接要求目标文件存在且条目已注册进 help.json。4. 术语一致性Terminology consistencyUI 字符串就是术语全文统一使用并与 Glossary.md 对齐。原文给出的反例一针见血不允许为了行文变化而在 frame parser / parser script / JS parser 之间轮换称呼也不允许偏离应用实际显示的文本。ss-docs 技能的 Rules 一节将此上升为全局不变量Keep the manuals terminology stable: the UI string is the term (Project Editor, frame parser, Setup panel) — no synonym rotation for variety. 这条启发式的落地方式是可操作的对任意术语先 grepapp/qml/**里的 UI 字符串确认应用实际显示什么再以该字符串作为手册术语。help.json 中 id 为javascript-api的条目标题即 Frame Parser Reference文件 JavaScript-API.md可见frame parser是贯穿手册与导航的统一术语。5. ground-truth 预防Ground-truth prevention这是十条中最重的一条也是量表与事实核查的交汇点每一个默认值、取值范围、UI 标签、快捷键、文件格式和门控断言都必须能对照core//app/src/app/qml验证——并且确实验证过原文直接引用了 ground-truth-factcheck.md 作为程序依据。量表给出了两个锚定判定写the app handles this automatically却不说明它实际做了什么得 1 分写错一个默认值得 0 分。factcheck 规程为这条启发式提供了操作化定义断言按kind分类默认值、范围/选项、UI 标签/菜单路径、版本门控、行为、文件/格式、CLI flag、交叉引用每类都指明 ground truth 在哪里——例如Data bits: 5, 6, 7, 8的 ground truth 是喂给 UI 的枚举、下拉框模型或校验器Reconnects automatically on disconnect的 ground truth 是实现该行为的 slot/handler。判定只有三种VERIFIED附file:line、WRONG附file:line 正确事实、NOT FOUND列出尝试过的搜索交给维护者不许猜。量表报告示例中的 P0 案例——Baud default documented as 115200; code says 9600——正是这条启发式失守的典型形态。6. 识别优先于回忆Recognition over recall读者跟随本页时永远不需要某个未命名页面的上下文行话要么就地定义要么链接到 Glossary.md前置条件要么点名要么给链接比较类内容用表格不埋在散文里。这条对应 E-E-A-T 翻译里的 Expertise 信号协议术语按行业用法使用parity、QoS、PGN并与 Glossary 一致。与启发式 3 的区别在于视角3 管读者能否自由进出页面6 管读者是否需要背诵未给出的上下文。7. 快读者与深读者的弹性Skimmer vs deep-reader flexibility阅读模式与内容形态必须匹配配置参数放表格、操作步骤用编号列表、原理用散文。快读者应该能不读原理部分就提取到他需要的那个参数。这是 Serial Studio 手册的标准页面形状ss-docs 新条目清单原话configuration tables, numbered quick starts, platform notes where behavior differs也是二阶检查中Uniform section shape反面的正面要求——真实的手册章节应当变化从 help.json 的 Drivers 分区规模可以看出UART、Modbus、OPC UA 各占一整页且形态各异而某些简单功能可能只需要一段话二阶检查原文即举此例UART needs a page, Process I/O needs a paragraph。8. 信息密度Information density每个段落都要挣得它的位置四条禁令首个实质断言之前不许有热身式开头throat-clearing intro不许有复述该节内容的总结段不许为让薄功能显得有深度而注水页面长度必须匹配功能范围。这一条与 second-order-tells.md 中的Wrap-up questions and summary paragraphs检查互为表里后者是结构级的检测手段In summary...段、What does this mean for you?式收尾本条是评分级的价值判断。9. 失败恢复Failure recovery页面必须预判那些设置跑不通的读者行为随平台差异的地方给平台注记常见故障给症状 成因更深层次的诊断在 Troubleshooting.md 里的就给链接。eeat-manual.md 把Platform caveats: Where behavior differs by OS, the page says so and says how列为 Trust 信号之一——平台差异不只是要提还要说清楚怎么个不同法例如 factcheck 规程中把port name examples的 ground truth 定位到平台相关字面量COM3、/dev/ttyUSB0这类值在代码里可查。10. 嵌入手册图Embedded in the manual graph页面必须是手册图manual graph的正式成员四个条件注册进 help.jsonid、title、section、file四字段齐全交叉链接双向运行本页链接它的亲戚页至少一个现有页面链接回来它引入的术语存在于 Glossary.md——若手册别处没有定义这些术语新条目要负责补进 Glossary不存在孤儿页面。ss-docs 技能的更新工作流将此写成硬性检查项New pages register indoc/help/help.json… and cross-link in both directions — the page links its relatives, and at least one existing page links back. 至少一个现有页面链回这一要求是 Serial Studio 特有的图完整性约束比通常的单向交叉引用更严格它保证从任意亲戚页都能走回新页面导航没有死胡同。评审报告格式量表规定了一份固定报告模板每条启发式一行含分数、严重级别与备注## Manual heuristics: page | # | Heuristic | Score | Severity | Note | |---|-----------|-------|----------|------| | 1 | Visibility of intent | 3 | P3 | Pro gating stated late | | 5 | Ground-truth prevention | 0 | P0 | Baud default documented as 115200; code says 9600 | | ... | ... | ... | ... | ... | ### Prioritized fixes - P0: ... - P1: ... - P2: ... - P3: ...使用时的要点表头page替换为被评审页面Note 列给出一句话证据性描述如示例中直接写出文档说 115200代码是 9600这种可追溯的事实落差Prioritized fixes 严格按 P0 → P3 排序与 ss-docs 评审工作流第 6 步Report prioritized P0 → P3对齐报告是只读产物评审模式下report — do not fix unless asked不允许静默修改文档。交叉验证规则量表与 factcheck 互锁量表末尾有一条自我审计规则原文为Cross-check against the factcheck verdicts: a page scoring 3 across the board while carrying a WRONG claim means heuristic 5 was scored without running the factcheck — run it.翻译成人话一个整体得分 3 的页面却背负着 WRONG 断言说明启发式 5 是在没有跑 factcheck 的情况下打的分——回去跑一遍。这条规则把量表变成一个可自证的系统factcheck 的判定喂给启发式 5 的分数反过来分数与判定的矛盾又暴露评分过程本身被跳过。它与 eeat-manual.md 的评分流一致——Trust 先行Trust: any WRONG claim, undisclosed gating, or oversold capability → page fails, stop其余信号随后评分。谱系从 Nielsen 十大可用性启发式到手册量表manual-heuristics 不是凭空设计的原文开篇交代了完整的改编链源头Nielsen 的 10 Usability HeuristicsNN/g1994 年2020 修订版——可用性工程的经典框架第一站claude-blog 项目的editorial-heuristics.mdMIT 许可把可用性启发式转译为博客编辑质量检查第二站经 impeccable 插件Apache 2.0的方法论传导再经 ss-docs SKILL.md 所述rescoped from SEO-blog writing to a technical manual替换内容博客侧的关切SEO 元数据、作者传记、E-E-A-T、FAQ schema被手册侧的关切取代——ground truth代码事实、edition gatingPro/Free 门控、help.json 导航图。值得注意的一个细节SKILL.md 说E-E-A-T survives the translation——它没有被丢弃而是以 eeat-manual.md 的形式转译为手册形态无署名、以具体性体现经验、以诚实范围体现可信度并作为评审工作流的独立一道门与启发式量表并行运行。量表负责结构与契约E-E-A-T 负责信任与深度factcheck 负责事实三者共同构成 ss-docs 评审的完整判据集。实操要点如何对一篇 doc/help 页面执行量表评审结合上述规则与 ss-docs 评审工作流对任意一篇手册页面的完整评审流程是先跑 linterpython scripts/documentation-verify.py doc/help/Page.md把词法级发现原样汇总不手工重复该脚本跳过代码围栏、行内代码、链接 URL 与 HTML 注释发现按 kind 分组如ai-marketing-phrase、ai-tutorial-voice、style-emdash-density等再跑二阶结构检查linter 干净后才进行按 second-order-tells.md 逐条报告命中抽取断言做 factcheck对每个可验证断言 grep 源码先精确匹配用户可见字符串再匹配符号给出 VERIFIED / WRONG / NOT FOUND 与file:line证据tests/ 可以佐证行为断言但永不替代实现代码作为 ground truth逐条打 0–4 分十条启发式独立评分其中第 5 条必须直接引用第 3 步的判定按 P0 → P3 排序输出修复清单WRONG 断言无条件 P0最后交叉验证检查分数与 factcheck 判定是否自洽不自洽则说明某一步被跳过重跑对应环节。一个实用的判断基准来自 eeat-manual.md 对 Experience 的最低要求一个没有可粘贴示例、没有具体数值、没有边界案例的页面等于用散文写的 UI 截图a UI screenshot in prose属 P1。这为量表第 7、8 两条阅读模式匹配、信息密度提供了可操作的及格线。小结manual-heuristics 量表的价值在于把这篇手册写得好不好这个主观判断压缩为十条可独立打分、可映射严重级别、可与事实核查互锁的客观判据。它与 ground-truth-factcheck.md事实、second-order-tells.md结构、eeat-manual.md信任共同构成 Serial Studio 文档质量的完整评审框架而 scripts/documentation-verify.py 与 doc/help/help.json 则分别提供了词法自动化检查与手册图注册的仓库侧锚点。对维护者而言这套量表既是新页面的写作自查清单也是评审他人提交时的统一裁判标准。【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-Studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考