我的写作原则
适用于 docs/ 下大多数分组的写作规范。docs/04-experience/(人生丰富)不适用本文——散文、游记类使用 散文写作。
适用分组
docs/01-health/健康幸福docs/02-capability/事业有成docs/03-wealth/财务自由docs/05-...吴飞飞(关于)
内容组织原则
- 内容按金字塔结构组织:先给核心结论,再往下展开细节。避免把所有知识点平铺罗列——覆盖面广不代表有洞见,浅入深出比面面俱到更有价值。
- 不在文档末尾添加总结段落,内容本身应自明。
- 不写"谁在什么时候的什么论文中说了什么",只陈述论点本身。必要时可以 Markdown 链接形式附上原文出处,但不在正文中展开归因。
- 避免使用"不是……而是……"句式。直接陈述正面结论,必要时用独立短句补充说明被排除的误解。
标题与结构
- 不使用"## X 反常识"类夸张标题(如"## 试用期管理最反常识的真理")。
- 不使用"## X 最关键 / 最核心 / 最根本 / 最重要的真理 / 判断 / 真相"等夸张定语作为标题。
- 统一用
## 一个判断或## 关键洞察等中性标题承载需要突出但不过度修饰的内容。 - 入口页(章节聚合的入口文档)不把哲学语录段(
>引用块)放在靠前位置。先有可执行内容(核心判断、原则列表、路径),再在适当位置放锚点段。 - 题记(文学引子、诗句引用等
>引用块)放在 H1 标题下、正文之前,不要放在文章开头(标题之前)。
数据与论据
不引用具体数字和统计数据作为论据(百分比、金额、精确时间段等)。用逻辑关系和因果机制来表达观点:具体数字会让文章显得像数据报道,而洞见来自逻辑,不来自数字。可以用定性描述替代("数百倍""断崖式下滑""以月计")。
表格
表格优先设计为纵向滚动:减少列(column)、增加行(row),兼容手机竖屏阅读。避免宽表格,必要时拆分为多个窄表格。
图标(icon)
frontmatter 中的 icon 字段必须真实存在:
- 使用
src/components/ItsHoverIcon/icons/下的实际文件名(如user-check-icon),或 - 使用
ICON_ALIASES(在src/components/ItsHoverIcon/index.tsx)中已注册的别名(如user、users)。
不要使用 ICON_ALIASES 中未注册、且对应文件名也不存在的别名(如 user-check 没有别名且文件名是 user-check-icon)。
文件操作
- 不添加注释,除非有非显而易见的原因需要说明。
- 不创建 README 或说明文档,除非用户明确要求。
- 新增文档优先复用现有文件,确认无合适位置后再新建。
- 移动文件会影响
sidebars.ts自动侧边栏和导航,操作前需确认影响范围(详见docusaurus配置)。
历史快照
带 演讲 徽标(frontmatter 含 sidebar_badge: { text: '演讲' })的文章属于历史快照,不修改正文。需更新观点时应复制为新文件后再编辑,原文件保留不动。详见 网站开发规范。
客观验证清单
每篇文章写完后,对照以下清单检查:
[ ] 0 处 "不是 X,而是 Y" 句式(除非是用户原话金句)
[ ] 0 处 "## 收尾" 节
[ ] 0 处名人引用("X 讲过 / 研究发现 / 强调..." 等)
[ ] 0 处 "## X 反常识" 类夸张标题
[ ] 0 处 "## X 最关键 / 最核心 / 最根本 / 最重要的真理 / 判断 / 真相" 类夸张标题
[ ] 入口页的 ">" 引用块(哲学语录)不在靠前位置
[ ] frontmatter 的 icon 字段在 ICON_ALIASES 中已注册或与真实文件名一致
[ ] 所有新文档带 description 字段(≤160 字)
[ ] `npm run build` 通过 [SUCCESS]