# Mj Book Writer

> Use when drafting a technical orange-book, handbook, or long-form guide that must feel like a knowledgeable human wrote it from use and judgment, not like official docs paraphrased into prose.

- Skill: `makerjackie/mj-book-writer` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add makerjackie/mj-book-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/makerjackie/mj-book-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: makerjackie (https://skillmd.com/u/makerjackie)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/makerjackie/mj-book-writer

---


# MJ Book Writer

写技术橙皮书，不是把官方文档翻译成中文。

这份 skill 吸收了 `makerjackie-writer` 里最有效的部分，但把目标换成了技术书写作：要讲人话，要有作者判断，要知道读者卡在哪里，同时又不能牺牲事实密度。

## 写作目标

- 像一个长期在用这个产品的人写的
- 读者能迅速知道“这东西是什么、好在哪、坑在哪、什么时候别用”
- 不照抄文档，不写成公关稿，也不写成空洞评论

## 核心方法

### 1. 先有“作者判断”，再有“事实堆叠”

每一章开写前，先写出 3 句内部草稿，不必出现在正文里：

- 我对这章主题的核心判断是什么
- 读者最容易误解的地方是什么
- 哪件事最值得提前说清楚

没有这 3 句，正文很容易沦为文档改写。

### 2. 永远从使用顺序切入，不从产品定义切入

技术书最容易写坏的地方，是第一段就变成“X 是一个……”。更好的顺序通常是：

1. 读者最可能先遇到的场景
2. 为什么大家会走到这一步
3. 这时 Cloudflare/某产品真正解决了什么
4. 再补官方定义

### 3. 写“选择”，不要只写“能力”

每章至少回答下面四个问题中的三个：

- 为什么有人会选它
- 为什么有人会误用它
- 它替代了什么麻烦
- 它不适合什么场景

### 4. 让事实层和判断层交替出现

理想节奏不是：

- 一大段事实
- 一大段总结

而是：

- 先抛一个判断
- 用一个官方事实或产品行为支撑
- 立刻解释这对读者意味着什么

### 5. 每章都要有“去文档腔”动作

至少做到其中两个：

- 把抽象名词换成真实使用动作
- 把产品能力换成“它帮你少操心什么”
- 把限制条件换成“你会在哪一步撞墙”
- 把组件关系换成“你该先学哪个、后学哪个”

## 推荐章法

### 开头

从一个真实使用入口切，不要从大词切。

好开头像这样：

- 很多人第一次用 Cloudflare，其实只是想把站点接上去。
- 大多数人不是为了学边缘计算才打开 Workers，而是因为原来的后端太笨重了。
- 讨论中国网络时，最容易犯的错，是把三件完全不同的事混成一件。

坏开头像这样：

- X 是业界领先的……
- 随着技术发展……
- 在当今时代……

### 主体

一章建议按下面的顺序推进：

1. 先说清读者为什么会关心这件事
2. 再说产品/能力怎么工作
3. 再说它解决了什么问题
4. 最后说边界、误区和建议

### 结尾

结尾不要写成“综上所述”。更好的收法是：

- 点明这章最重要的取舍
- 告诉读者下一章为什么要继续看
- 或把一个常见误解轻轻纠正回来

## 语言要求

### 应该多用

- “很多人第一次……”
- “真正麻烦的地方在于……”
- “这也是为什么……”
- “更准确的说法是……”
- “别把它想成……，更像……”
- “如果你已经走到这一步……”

### 应该少用

- “赋能”
- “全面覆盖”
- “显著提升”
- “本质上”
- “换句话说”
- “意味着什么”
- “说白了”
- “首先、其次、最后”

## 反 AI 味检查

写完每章，至少过这 6 条：

1. 第一段是不是像文档导语
2. 有没有连续三句都在解释概念，没有真实场景
3. 有没有“既……又……”这种平滑到发假的句式
4. 有没有把限制写得过于轻描淡写
5. 有没有只写优点，不写误用成本
6. 有没有作者自己的判断

## Cloudflare 专项提醒

### 1. 少写产品目录，多写产品关系

不要为了“全”把每个产品都写得一样重。读者真正需要的是：

- 应该先学谁
- 谁跟谁最常一起出现
- 哪些产品看着像一类，其实解决的不是同一个问题

### 2. 中国章节必须拆线

永远分成三条线：

- 默认全球网络体验
- 官方 China Network
- 社区优选节点 / 优选 IP

### 3. 避免假装全知

对于价格、限额、可用区域、产品支持范围这些容易变化的内容：

- 能不写数字就不写数字
- 必须写时只引用最新官方资料
- 正文里优先写决策逻辑，不要把章节写成 changelog

## 一章的完成标准

- 读完能复述这个产品/主题的核心作用
- 读完知道它适不适合自己
- 读完知道下一步该学什么
- 读完不会觉得这是官方文档换皮