内容编写指引

本页讨论的是「怎样把一篇物理内容写成适合学习的页面」．Markdown 语法、排版、LaTeX 和文件存储规则仍以格式手册为准；本页更关心的是叙事、结构、例题和读者体验．

目标读者

Physics Learning Wiki 当前优先服务两类读者：

第一次系统接触该主题的本科生．
已有零散基础、但缺少整体框架的自学者．

因此，一篇页面首先要能帮助读者建立主线，而不是优先追求炫技、信息密度或「把所有细节一次讲完」．

总原则

先回答「为什么要学这个」，再给定义、定律和公式．
每一页都要告诉读者：本页在解决什么问题、依赖什么先修、读完后应该去哪里．
先建立物理图像，再补数学表达；先给主线，再放补充．
例题服务于概念，不要让大量运算把主线淹没．
如果一段内容只适合已经学过该主题的人，应明确标成「进阶补充」，不要塞进主线正文．

关于 ??? note、??? warning、???+ note 等信息框应该装什么内容，见信息框与补充内容规范．

Why 推进写法

对于初学者，最容易失去兴趣的时刻往往不是「公式很难」，而是「不知道这里为什么突然要定义一个新量」．因此，建议在页面开头明确回答以下问题：

眼前的现象或困难是什么．
旧工具为什么不够用．
这页引入的新概念到底解决了什么问题．
学完这页后，读者应该能判断什么、解释什么、计算什么．

一个常见的四步写法是：

从一个真实现象、典型题目或常见困惑切入．
指出直觉解释或旧概念的局限．
引入本页的新概念、新模型或新定律．
给出「学完本页你应该得到什么能力」的说明．

例题应该怎么写

例题不是为了展示作者会算，而是为了帮助读者学会建模和判断．建议每道例题至少回答下面六个问题：

这道题为什么放在这里．
它训练的核心能力是什么．
题目中的系统、对象和假设是什么．
解题时为什么选用这组物理量、方程或守恒律．
结果的物理意义是什么．
初学者最容易错在哪里．

例题推荐模板

可以参考下面的顺序组织例题：

题目背景：只保留理解问题所需的条件．
设定与假设：说明研究对象、理想化条件、符号和正负号约定．
建模：指出使用哪条定律、哪种守恒关系或哪种近似．
推导：展示关键步骤，不要无说明地大跳步．
结果解释：解释结果为什么合理，必要时讨论极限情形．
易错点：指出最常见的概念混淆、符号错误或适用条件误用．

如果题目来自教材、竞赛或公开题库，请尽量注明来源；如果题目过长，应当在不改变物理本质的前提下进行必要压缩．

常见写作问题

只有定义和公式，没有问题意识，读者不知道这一页为什么存在．
只讲推导，不讲物理图像，读者会算但不会解释．
例题步骤过于简略，关键假设和变量定义缺失．
把进阶细节和主线正文混在一起，初学者第一遍就被淹没．
章节之间没有连接，读者学完一页不知道下一步该看什么．

页面元数据与搜索索引

页面的内容状态决定其搜索索引状态，页面元数据应随内容一起维护．

正式知识页

普通正式页面默认允许搜索引擎 index, follow，并会在构建时进入 sitemap，不需要手工添加 robots: index．重要的入口页和核心知识页可以在 frontmatter 中添加独立的 description，准确说明本页学什么、能解决什么问题．description 应该符合页面真实内容、彼此独立、使用自然中文，不要承诺正文没有提供的内容．

建设页

如果页面正文暂时只是精确的 TO DO，必须显式标记为 noindex, follow：

---
meta:
  - name: robots
    content: noindex, follow
---

页面内容完成后，按下面的顺序发布：

删除 robots 中的 noindex．
检查页面标题和正文结构．
如果页面是关键入口或核心知识页，补充独立 description．
执行构建并检查最终 HTML．
运行 SEO checker，确认页面自动进入 sitemap．

不需要手工编辑 sitemap；内容完成并移除 noindex 后，构建流程会根据最终 HTML 自动更新它．

内部工程资料

planning、spec 和 ADR 等内部工程资料不应进入公开 build，应放在已经被 exclude_docs 覆盖的目录中．不要为了让它们不被索引而把它们当作公开知识页维护．

不要做的事情

不使用 meta keywords．
不手工设置 sitemap 的 priority 或 changefreq．
不为了 SEO 重复堆砌关键词．
不为未完成页面编造 description．
不伪造 sitemap 的 lastmod．

本站目前部署在 GitHub Pages 子路径 https://physics-learning-wiki.github.io/Physics-Learning-Wiki/ 下．项目子路径中的 robots.txt 不是主机根目录的 robots 文件，因此不要在 docs/ 下创建一个看似有效的 robots.txt；未来迁移到自定义域名时，再配置真正位于主机顶层的 /robots.txt．

发布前自检

在提交页面前，建议至少检查下面几件事：

一个第一次接触该主题的读者，能否从前两段看出这页的目的．
每个新符号是否在首次出现时被定义．
是否明确说明了公式或模型的适用条件．
是否至少有一个能体现核心思想的例题或例子．
是否提示了常见误区、反例或失效条件．
是否给出了前置页面和后续页面的连接．
是否区分了主线正文与补充内容．

章节补充说明

总规范之外，各学科还应该有自己的章节级说明，用来规定叙事重点、常见误区和例题风格．目前已经开始建设的示例是：

后续实验物理、计算物理与工具，以及更细分的学科子模块也应逐步补齐各自的章节说明．

本页面最近更新：2026/8/27 16:53:36，更新历史
发现错误？想一起完善？在 GitHub 上编辑此页！
本页面贡献者：Leafuke, Physics Learning Wiki
本页面的全部内容在 CC BY-SA 4.0 和 SATA 协议之条款下提供，附加条款亦可能应用

内容编写指引