主题
界面
技术写作与博客
1. 本节定位
写作是技术人杠杆最高的输出 —— 一次投入，被反复检索与引用； 而它的质量可以量化体检。
★ 本节用工具对一篇真实讲义做三层体检（实测 6/6 满分） ✓✓：
text
体检对象：docs/06-java-deep/jvm/S6-010.md（GC 日志分析与 JVM 调优）
【结构】标题 24 个（二级 14）；✓ 结论先行；✓ 表格 4 张
【密度】代码块 11 个；数字 437 次（每 100 字 6.2 个）；✓ 无超长段落
【表达】✓ 未发现套路化词汇；✓ 结论句 10 条
总分：6/6 ✓✓✓★ 工具：python -X utf8 scripts/growth/article_lint.py [你的文章.md] ✓
2. 学习目标
- 会用三层体检（结构 / 密度 / 表达）自检文章 ★★★；
- 掌握「结论 + 证据 + 行动」的三段结构 ★★★；
- 能识别并清除「AI 味与空话」★★★；
- 有可持续的选题与更新节奏 ★★。
3. 前置知识检查
- 有过把一件事讲清楚的经验吗？（《团队分享与知识输出》 的分享同理）✓
- 有自己的项目或实验可写吗？（《简历与项目描述》 的简历素材可直接复用）✓
4. 为什么需要这个知识
★ 写作的四个复利 ✓✓✓：
| 收益 | 说明 |
|---|---|
| 想清楚 | 写不出来的地方 = 没想清楚的地方 ✓✓✓ |
| 被看见 | 面试、晋升、内推，都需要「可展示的证据」✓✓ |
| 可复用 | 一次解释，回答 N 次相同的问题 ✓ |
| 建体系 | 200 节课程就是 200 次「结构化输出」的复利 ✓✓✓ |
5. 核心概念
5.1 三层体检：把「写得好不好」变成可测的（实测）★★★
| 层 | 检查项 | 判据 |
|---|---|---|
| 结构 | 结论先行？表格？ | 前 5 个标题里要有「结论/定位」✓✓ |
| 密度 | 代码块数、数字密度、长段落 | 代码块 ≥ 3；数字 ≥ 每百字 3 个 ✓✓✓ |
| 表达 | 空话词、结论句 | 无「赋能/抓手/在当今」；有 ★ 结论句 ✓✓ |
★ 实测输出（节选） ✓✓：
text
【第二层：密度（信息量）】
代码块 11 个；数字出现 437 次（每 100 字 6.2 个）
✓ 代码/输出块 ≥ 3（技术文要有「可验证的东西」）
✓ 数字密度 ≥ 3%（**数字比形容词可信**）
【第三层：表达（有没有 AI 味 / 空话）】
✓ 未发现套路化词汇
✓ 有显式结论句（★ 标注）10 条 —— **读者只记得结论**5.2 三段结构：结论 + 证据 + 行动 ★★★
text
① 结论（开头就说）：这问题是什么、答案是什么 —— 不铺垫 ✗✓
② 证据（中段）：实测数据、代码、输出 —— **可复现** ✓✓✓
③ 行动（结尾）：读者今天能做什么（一条具体动作）✓✓★ 对照本知识库的讲义 ✓✓：每节都是这个结构（本节定位 = 结论；实测输出 = 证据； 动手实验/验收方式 = 行动）—— 模板可以照抄 ✓✓✓。
5.3 数字与代码：可信度的来源 ★★★
★ 两条替换规则 ✓✓✓：
| 原来的写法 ✗ | 改成 ✓ |
|---|---|
| 「性能提升明显」 | 「QPS +25% / P99 从 12ms 降到 4.2ms」✓ |
| 「遇到过内存问题」 | 「64M 堆下存活量顶住上限，Full GC 5 次后 OOM」✓✓ |
| 「用了很多测试」 | 「172 个用例（单元/切片/集成/UI 四类）」✓ |
★★ 原则 ✓✓✓：写下的每个数字都要能复现 —— 不能复现的数字，宁可不写 ✓。
5.4 AI 味与空话：清单式清除 ★★★
★ 高频空话（写完全文搜一遍） ✗：
text
在当今 / 随着…的发展 / 众所周知 / 值得注意的是 / 总而言之 / 综上所述
赋能 / 抓手 / 闭环 / 生态 / 深度融合 / 极大地 / 显著地★ 清除方式 ✓✓：删掉，或换成具体事实 —— 「值得注意的是，缓存会带来一致性挑战」→「缓存与库不一致的窗口是 200ms（实测）」✓✓✓。
5.5 选题与节奏 ★★
| 选题来源 | 例子 |
|---|---|
| 一次排查（最优先）✓✓ | 「线上 CPU 100% 的 18 分钟定位过程」 |
| 一次实验（本知识库模式）✓✓ | 「四种限流算法对拍」 |
| 一个概念的澄清 ✓ | 「volatile 的可见性到底保证了什么」 |
| 节奏 | 每周 1 篇（600-1500 字）> 每月 1 篇长文 ✗✓ |
6. 递进示例
6.1 用工具体检自己的文章
powershell
python -X utf8 scripts/growth/article_lint.py docs/你的文章.md6.2 改稿顺序（比一上来改结构快）
text
① 删空话（最快、收益立竿见影）
② 补数字与代码（可信度）
③ 调结构（结论先行、加表格）
④ 最后通读一遍，删掉多余的 20% ✓✓6.3 反例：把「学习笔记」当博客发
text
「今天学习了 Redis 缓存，记录一下」✗（没结论、没证据、没行动）
正解：「缓存三病：一次实测把三者的边界分清了」+ 数据 + 一条行动 ✓✓✓7. 完整可运行工具与实测
工具：scripts/growth/article_lint.py
运行：
powershell
python -X utf8 scripts/growth/article_lint.py实测输出（节选）：
text
===== 技术写作体检：docs\06-java-deep\jvm\S6-010.md =====
总行数 274；字符数 7082
✓ 开篇有「结论先行」（本节定位 / 结论）
✓ 用了表格（4 张）—— 对比类信息用表格更省读者时间
代码块 11 个；数字出现 437 次（每 100 字 6.2 个）
===== 总分：6/6 =====
★ 写作的检验标准只有一条：**读者能不能在 3 分钟内拿到「结论 + 证据 + 行动」** ✓✓✓8. Debug 观察点
- 拿一篇你自己写的东西跑工具：看哪层失分最多 ✓✓；
- 故意写一段「AI 风」文字跑一遍：观察空话词报警 ✓✓；
- 把一篇长文删到 2/3：对比可读性（通常更好）✓✓；
- 找一位非本领域的朋友读 3 分钟：让他复述「结论是什么」（复述不出 = 结构有问题）✓✓✓。
9. 常见错误
| # | 错误 | 说明 |
|---|---|---|
| 1 | 铺垫太久（"在当今…"） ✗✗ | 结论先行 ✓ |
| 2 | 只有形容词没有数字 ✗✗✗ | 数字比形容词可信 ✓✓ |
| 3 | 长段落一屏读不完 ✗ | 拆成列表/表格 ✓ |
| 4 | 没有结尾行动 ✗ | 加一条具体动作 ✓ |
| 5 | 追求长文 ✗ | 600-1500 字讲透一件事 ✓✓ |
| 6 | 发完不更新 ✗ | 半年回看补一次数据（版本变化）✓ |
10. 动手实验
- 跑工具体检本知识库的任意 3 篇讲义：观察分数分布 ✓✓；
- 写一篇 600 字短文（选题：你最近一次排查或实验），改到 ≥ 5/6 分 ✓✓✓；
- 把这篇文章给同事读，收集「复述结论」的准确率 ✓✓；
- 把文章发布到任意平台（或团队 wiki），两周后看反馈 ✓。
验收方式：产出一篇 ≥ 5/6 分的文章，且同事能在 3 分钟内复述其结论。
扩展任务：把文章改写成「一页分享稿」（《团队分享与知识输出》），做一次 10 分钟团队分享 ✓✓
11. 练习题
- 三层体检各查什么？判据是什么？
- 「结论 + 证据 + 行动」分别对应文章的哪里？
- 为什么「数字比形容词可信」？写数字的前提是什么？
- 常见的 AI 味/空话词有哪些？怎么处理？
- 改稿的正确顺序？
参考答案（要点）
- 结构（结论先行/表格）/ 密度（代码块、数字、段落）/ 表达（空话、结论句） ✓✓★
- 开头结论 / 中段证据 / 结尾行动 ✓✓★
- 数字可验证、可复现；前提是能复现 ✓✓★
- 「在当今/赋能/抓手/值得注意的是…」；删掉或换具体事实 ✓✓★
- 删空话 → 补数字 → 调结构 → 通读删 20% ✓✓★
12. 掌握标准
- [ ] 会用三层体检自检 ★★★；
- [ ] 会按「结论 + 证据 + 行动」组织 ★★★；
- [ ] 能清除空话并补足数字 ★★★；
- [ ] 有稳定选题与更新节奏 ★★。
13. 扩展资源
- 技术写作指南（Google）
- 《GC 日志分析与 JVM 调优》（本节体检的样例文章）
14. 下一步学习
《架构案例与解决方案沉淀》 架构案例与解决方案沉淀 —— 把写作升级成「可复用的解决方案资产」。
前置知识
无，可直接开始
后续知识
暂无
进度只保存在本机浏览器，可随时清除