技术文档表达优化分析

第 2 页 · 文字预览

我们积累了 4 个版本的技术文档

2 / 12

从「素材入口 → 视频创作 → 飞书触发 → PPT 输出」，一条进化链

v0.1.2

markitdown

converter Skill

任意文件

→ Markdown

GitHub 开源

AI 安装指引

📥 素材入口

→

v0.1.3

HyperFrames

视频创作环境

AI 写视频动效

→ 导出 MP4

HTML → 视频

FFmpeg 渲染

🎬 视觉表达

→

v0.1.4

飞书 CLI

远程控制 Obsidian

手机发消息

→ 触发后端任务

cc-connect 守护

移动端操作

📱 即时触发

→

v0.1.5

ppt-master

AI PPT 系统

Markdown 笔记

→ 原生可编辑 PPTX

DrawingML 形状

77KB / 12页

📊 汇报呈现

辅助项目：微信驱动 Claude 方案 — 设计 / 协议 / 实测 / 开源蓝图（~6 篇）

来源：产品迭代录 ProjectMap

第 3 页 · 文字预览

表达风格诊断：5 项做得好，4 项可优化

3 / 12

用《金字塔原理》4 条铁律逐项审查当前文档

✅ 已做得很好的 5 项

分类意识强

每篇分 Part 1/Part 2，章节目录清晰，表格对比得当

关键决策点标记

⚠️ 关键决策点 #N 提示，帮读者在分叉路口不迷路

检查清单

每个部署末尾都有可勾选的 checklist，逐项确认

图文并茂

流程图、代码块、对比表穿插，可视化程度高

面向小白用户设计

每条命令可复制执行，前置条件明确

🔧 可优化的 4 项

缺少 SCQA 开篇钩子

汇报场景下，开头没有制造"冲突"，听众 30 秒内走神

标题写的是"主题"而非"结论"

"部署前准备"→应改为"部署前要准备 3 件东西"

段落内部缺少"结论先行"

每段第一句常是铺垫，读者要读到中间才找到重点

跨版本叙事缺少"金字塔骨架"

4 版各自独立，没有统一中心思想串成论证链条

诊断标准：《金字塔原理》4 条铁律 — 结论先行 · 以上统下 · 归类分组 · 逻辑递进

第 4 页 · 文字预览

优化点 ①+②：缺 SCQA 钩子 × 标题是主题非结论

4 / 12

❶ 缺少 SCQA 开篇钩子

来源：《金字塔原理》§03 序言的 SCQA 结构

当前写法（主题式开头）

"ppt-master 部署指南（Part 1：环境搭建 + 安装 + 验证）"

"适用对象：小白用户，配合 AI 一键部署。"

→ 告知型开头，没有制造"为什么我要听"的紧迫感

SCQA 四要素

S 背景

读者已知的事实，让他点头

C 冲突

打破平静的事，让他紧张

Q 疑问

他自然想问什么

A 回答

你的中心思想

💡 汇报前 30 秒决定听众是否继续听。SCQA 就是这 30 秒的脚本。

变体选择（基于读者关系）

给老板汇报 → 开门见山式

A→S→C：先甩结论，再补背景

"建议立即改定价策略——因为 Q1 降了 15%"

对外提案 → 突出信心式

Q→S→C→A：先抛吸引人的问题

"怎么用最少成本在 90 天回升 12%？"

❷ 标题是"主题"而非"结论"

来源：《金字塔原理》§06 演示的逻辑 — "标题就是结论"

主题式标题（当前）

结论式标题（优化）

部署前准备

部署需要 3 件东西，其中 1 件已被墙

完整工作流

7 步工作流，只有 1 步需要你确认

常见问题速查

3 个常见坑，90% 的人踩过第 2 个

一、ppt-master 是什么？

你的 AI PPT 工具链：从笔记到原生 PPTX，只需要说 1 个字

金字塔原理铁律

"幻灯片每一页只讲一个思想——而且这个思想应该明明白白写在标题里。标题不要写'销售情况'，要写'Q1 销售下降 15%'。"

100%

把所有页的标题抽出来

连起来读，应构成完整论证

12 词

幻灯片标题不超过

12 词为佳

第 5 页 · 文字预览

优化点 ③+④：缺结论先行 × 跨版本缺骨架

5 / 12

❸ 段落内部缺少"结论先行"

来源：《金字塔原理》§01 四条铁律之首

当前写法（先列细节再给结论）

"所有 SVG 生成完毕后，AI 会自动运行：

python3 skills/ppt-master/scripts/svg_quality_checker.py...

检查项：

- ❌ error：被禁 SVG 特性→必须修复

- ⚠️ warning：低分辨率→能修就修"

优化后（结论先行 + 归类分组）

"SVG 生成完毕后，AI 会自动做一次质量检查。检查分两个等级："

🔴 error：使用被禁 SVG 特性 → 阻塞，必须修复

🟡 warning：低分辨率、非安全字体 → 不阻塞，能修就修

→ 第一句就给出了这段的中心思想

金字塔原理铁律："结论先行"

"每一篇文章、每一段落、每一个层级，有且只有一个中心思想，而且必须放在最前面。大脑读信息的方式——先看到结论，才知道接下来的细节'装到哪个篮子里'。"

❹ 跨版本叙事缺少"金字塔骨架"

来源：《金字塔原理》§01 — "以上统下"失败

当前状态：4 个版本各自独立

v0.1.2

v0.1.3

v0.1.4

v0.1.5

← 散落

没有中心

应有的状态：金字塔骨架

中心思想：

4 次迭代，打通"输入→创作→触发→输出"闭环

v0.1.2 输入层

v0.1.3 创作层

v0.1.4 触发层

v0.1.5 输出层

🎯 效果：

4 个版本不再是 4 个独立故事，而是一个完整论证链条的 4 个论据

听众从头到尾跟着一条主线走，而非不断切换频道

第 6 页 · 文字预览

核心方案

给技术汇报搭金字塔骨架

4 次迭代 = 一个 MECE 闭环："输入 → 创作 → 触发 → 输出"

中心思想：打通 AI 工具链完整闭环

输入层

v0.1.2 · 任何文件 → Markdown · 打通素材入口

创作层

v0.1.3 · Markdown → 视频 · 打通视觉表达

触发层

v0.1.4 · 飞书消息 → 远程执行 · 打通移动控制

输出层

v0.1.5 · Markdown → 原生 PPTX · 打通汇报呈现

→

⟳

闭环

MECE

🎯 这 4 层的关系是 MECE（互相独立、完全穷尽）

不需要增加第 5 层来"补齐"，也没有哪两层做的事情重叠——这就是"归类分组"中最高标准的结构

告诉听众：4 次迭代不是随机发生的，而是围绕"一条工作流"的 4 步进化

金字塔原理铁律 3+4：归类分组（同一逻辑范畴）+ 逻辑递进（程度顺序：从基础到高级）

6 / 12

第 7 页 · 文字预览

用 SCQA 重构开篇，30 秒定调

7 / 12

选择"开门见山式"（A→S→C），因为汇报对象是熟悉你的团队

❌ 当前：流水账式开篇

"今天我给大家汇报一下

我们产品的 4 次迭代。

第一次是 markitdown-converter，

主要解决……

第二次是 HyperFrames……"

问题诊断

• 没有背景（S），听众不知道"为什么是这 4 个"

• 没有冲突（C），没有制造"为什么要听"的理由

• 框架感弱，像在念目录

✅ 优化：开门见山式 SCQA

A 结论先行

"4 次迭代走下来，我用 AI 工具链打通了从素材到输出的完整闭环——

现在用手机发条飞书消息，就能自动生成一份可编辑的 PPTX。"

S 背景：半年前我的工作流是：找素材→手动整理→打开多个软件→反复调整格式→发文件

C 冲突：每一环节都在消耗创造力——真正花在"思考"上的时间不到 20%

Q 隐含疑问：能不能让 AI 把中间的脏活全干了？

A 展开：今天分享 4 次迭代，一条"懒人工作流"的进化史。

从素材入口→视频创作→飞书触发→PPT 输出，全部由 AI 打通。

🎯 听众 30 秒内知道：为什么听、你有什么结论、听起来有没有价值

SCQA 4 种变体：标准式 · 开门见山式 · 突出忧虑式 · 突出信心式 — 按读者关系选择

第 8 页 · 文字预览

关键决策点 → 冲突点，制造叙事张力

8 / 12

把文档中的⚠️标记升级为💥冲突钩子，听众从被动接收变为主动追踪答案

当前表达（叙述型）

⚠️ 你的网络能否直连 github.com？

这决定了用方案 A 还是方案 B

像选择题题干，没有紧迫感

优化后（冲突型）

💥 第 1 关：GitHub 被墙了

两条路，走错一条白干 1 小时

制造"闯关"感，听众想听下去

当前

⚠️ 这一步是整个流程唯一的阻塞步骤

确认后全自动

描述性的，缺乏"错了会怎样"

优化后

💥 整个流程你只需要说 1 个字

但说错就全歪了

制造风险，提升参与度

当前

⚠️ PYTHONPATH 配置（最容易忘的一步）

如果不设，运行任何脚本都会报错

像备忘，不是预警

优化后

💥 部署中最隐形的坑

忘了它，所有 import 全报错

"隐形坑"比"容易忘"更有力

原理：SCQA 中的 C（冲突）制造紧张感——冲突 = 读者已知的世界被打破。听众大脑对"被打破"天然敏感。

第 9 页 · 文字预览

段落级改写：结论先行 + 归类分组

9 / 12

❌ 当前写法（先列细节，再给含义）

来源：v0.1.5 实战指南 §7.4 质量检查

"所有 SVG 生成完毕后，

AI 会自动运行：

python3 skills/.../svg_quality_checker.py

检查项：

- ❌ error：使用被禁 SVG 特性

→ 必须修复再继续

- ⚠️ warning：低分辨率图片

→ 能修就修，不阻塞"

金字塔原理铁律 #1 违反：结论先行

→ 这段开头第一句没有给出"这段的中心思想是什么"

→ 读者要读到列表才推断："哦，这是在讲两级检查"

✅ 优化后（先说结论，再列论据）

第 1 句是结论 ← 这一段的核心

"SVG 生成完毕后，AI 会自动做一次质量检查。

检查分两个等级——一票否决的错误和可忽略的警告。"

归类分组（铁律 #3）

🔴 error

使用了被禁的 SVG 特性

→ 阻塞，必须修复才能继续

🟡 warning

低分辨率图片、非安全字体

→ 不阻塞，能修就修

改写要点

① 首句给出结论（"做一次质量检查，分两个等级"）

② 两个等级用表格/卡片并列，而非无序列表——属于"归类分组"

1 秒

读者定位中心思想

2 眼

区分严重等级

第 10 页 · 文字预览

导航语体系 + 从《认知觉醒》借清晰力

10 / 12

🗺️ 跨文档导航语

金字塔原理：汇报中不断给听众"导航"，防止走丢

┌──────────────────────────────────────┐

│ 你现在在 → 产品迭代录 → v0.1.5 │

│ │

│ 已经走过的路： │

│ v0.1.2 素材入口 ✓ → v0.1.3 视频创作 ✓ │

│ → v0.1.4 飞书触发 ✓ │

│ │

│ 这一站：Markdown → 原生 PPTX（终点站） │

└──────────────────────────────────────┘

为什么需要导航语？

• 汇报听众的注意力曲线是 U 形——中间会走神

• 金字塔原理规则："每过几页回到金字塔顶"

• 导航语 = 口头汇报中的"以上是 X，接下来讲 Y"

📍 放在每份文档开头（只占 8 行），读者瞬间知道"在全局的哪个位置"

从"4 个孤立岛屿"变成"一条有地图的旅程"

✨ 从《认知觉醒》借一个方法：清晰力

模糊是焦虑的根源，清晰是行动的起点

应用到技术文档：每句话都要回答一个明确的问题

模糊的指令（当前）

"帮我把 [你的笔记路径/主题] 做成一份 PPT。"

→ 小白不知道路径怎么写，主题怎么描述

清晰的指令（优化后）

你只需要给 AI 说 3 样东西，其他全自动

① 素材在哪（粘贴文件路径，或说"笔记中的 XX 主题"）

② 风格偏好（可选：科技风/极简风/商务风，默认商务）

③ 大概页数（可选：默认 12 页）

示范命令："帮我把书籍拆解/金字塔原理/ 下的 8 篇笔记做成 PPT，商务风，12 页"

💡 核心洞察

"帮我把XX做成PPT"对 AI 来说足够，但对不知道路径的小白来说完全是模糊的

🎯 效果：

把"路径怎么写"这个模糊恐惧，变成 3 个填空题

清晰力 = 降低行动门槛 = 更多人真的会用

第 11 页 · 文字预览

金字塔自检清单：每次写文档前过一遍

11 / 12

来源：《金字塔原理》§07 可复用模板与检查清单 — 8 项全过 = 合格的金字塔

中心思想

能用一句话写出来吗？

✅ 结论先行（铁律 #1）

标题

写的是"结论"不是"主题"？

✅ 标题即结论

开篇

30 秒用 SCQA 抓住了吗？

✅ SCQA 序言

段落

每段第一句是结论吗？

✅ 以上统下（铁律 #2）

归类

同级要点是同一逻辑范畴吗？

✅ 归类分组（铁律 #3）

顺序

按时间/结构/程度排列了吗？

✅ 逻辑递进（铁律 #4）

导航

有给听众导航吗？

✅ 位置感 + 过渡语

结尾

有明确的行动呼吁吗？

✅ Call to Action

8 项全过 → 合格的金字塔

少 1 项 → 重写。每项都是可独立验证的，不存在"可能OK"的灰色地带。

来源：《金字塔原理》§01 金字塔自检 4 题 + §06 演示自检 4 题 → 合并为 8 题

"文章写不清楚，往往不是语言问题，是思考问题。"

— 芭芭拉·明托，《金字塔原理》

第 12 页 · 文字预览

4 次迭代，一个闭环

内容不缺，缺的是钩子、骨架和节奏

SCQA

钩子

开篇 30 秒，制造冲突

让听众带着问题听下去

MECE

骨架

金字塔分层，4 层闭环

互相独立、完全穷尽

CTA

节奏

导航语 + 清晰力

结尾有行动呼吁

下一步：从 4 份文档中挑 1 篇，用这套方法逐段重写

每次写文档前跑一遍 8 项自检清单 → 表达力翻倍

方法来源：芭芭拉·明托《金字塔原理》· 周岭《认知觉醒》

数据来源：产品迭代录 v0.1.2 — v0.1.5 全部技术文档

第 1 页 · 文字预览