跳转至

内容编写指引

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

目标读者

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

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

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

总原则

  1. 先回答「为什么要学这个」，再给定义、定律和公式．
  2. 每一页都要告诉读者：本页在解决什么问题、依赖什么先修、读完后应该去哪里．
  3. 先建立物理图像，再补数学表达；先给主线，再放补充．
  4. 例题服务于概念，不要让大量运算把主线淹没．
  5. 如果一段内容只适合已经学过该主题的人，应明确标成「进阶补充」，不要塞进主线正文．
  6. 正文按物理知识领域唯一存储，课程与学习阶段通过路线页组织：避免因学校开课需要而新建重复平行的正文目录（例如理论力学直接复用质点、刚体与分析力学正文，电动力学复用电磁学正文）．

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

术语与译名约定

术语应帮助读者识别同一个概念，避免同一推导无说明地更换叫法．术语速查见 术语表；数学记号仍以 数学符号表 为准．本表约定正文主词，不将合理别名或跨语境用法视为知识错误．

语境正文主词与说明
抽象线性代数向量、特征值、特征向量
物理几何量与场矢量、位置矢量（位矢）；曲线坐标的基向量等数学叫法可以保留
数学与场论微分映射算子；Sturm–Liouville 问题用微分算子
量子态与观测量算符、本征值、本征态；量子应用段不因出现在数学章节而改成另一套叫法
振动与相对论固有频率、固有角频率；固有时、固有长度等相对论名称保留
热学状态与过程物态方程（亦称状态方程）、等体过程（亦称等容过程）、定容热容、定压热容
热学量名热容、比热容、物质的量、黏滞；一般气相物质用蒸气，蒸汽设备等固定行业名称可保留
物理与数学常量普朗克常量、玻尔兹曼常量、气体常量；数学常数、积分常数、介电常数等按其含义保留
全称与简称惯性参考系/惯性系、质心参考系/质心系等可以共存；质点系统正文优先称质点系

热学统一以 AA 表示系统对外做功，A>0A>0 表示能量以功的方式流出系统，以 Q>0Q>0 表示吸热，第一定律为 Q=ΔU+AQ=Delta U+A．制冷机输入功的正值大小写为 Ain=−A>0A_rm in=-A>0．对照其他资料的 WonW_rm on 等记号时必须明确给出换算，不能在正文中悄然换用另一套正负号．摩尔热容用 CV,mC_V,m、Cp,mC_p,m 等，总热容用 CVC_V、CpC_p，并明确 CV=νCV,mC_V=nu C_V,m．

译名沿用 项目方针 的通行名原则．正文主名为费曼、海森堡、菲涅尔、范德瓦尔斯、史瓦西、约当；首次出现补英文，其他译名在术语表登记．英文缩写、软件标识、代码、引用原文及资源路径不机械中文化．玻恩/波恩等确实指错人的写法应纠正；有争议的译名不能仅因字形不同列为知识错误．

同句出现向量与矢量、算子与算符可能是在比较语境或解释别名，应核对所指对象，不能仅凭共现判错．符号表作为数学记号目录可以使用通用的「向量」；正文描述物理量时按本节语境区分．

概念引用与页面先修

正文在第一次有教学意义地需要某个概念时，可以显式引用：

1
由牛顿第二定律，我们得到一个[微分方程](concept:differential-equation)．

作者选择引用位置与显示文字，构建系统负责解释和正文入口．同一概念后续重复出现通常保持普通文本，不自动标注关键词．段落、列表、表格和信息框支持引用；首版不支持标题或图片中的引用，代码和公式中的语法示例保持原样．引用文字可以使用符合语境的别名，不必与主名完全相同．

构建后，正文概念链接在便签可用时点击展开解释，并提供「阅读完整内容」入口；无 JavaScript、浏览器不支持或资源加载失败时直接跳转．GitHub 源码预览不能直接打开 concept: 链接，请使用本地构建或站点预览检查．

页面可在现有 frontmatter 中声明直接先修：

1
2
3
prerequisites:
  - derivative
  - differential-equation

构建按作者顺序生成「本页需要」，点击直接进入学习页面．不自动推导依赖，也不要求正文引用都列为先修．需要掌握到什么程度，应在导读中说明．未声明时不显示先修区域．

概念维护在仓库根目录的 data/concepts.yml，最小条目如下：

1
2
3
4
5
6
7
version: 1
concepts:
  differential-equation:
    name: 微分方程
    english: Differential equation
    summary: 将未知函数及其导数联系起来的方程。
    target: math/differential-equations/ode-intro.md

ID 使用小写英文字母、数字和连接符，以字母开头；命名应稳定，不随页面改名而修改．name、summary、target 必填，english 和字符串列表 aliases 可选．target 相对于 docs/，可以带 #anchor．别名只用于显示与审校，不触发自动匹配．短释义建议一至两句，说明必要的适用条件；首版按纯文本输出，不解析 Markdown、HTML 或公式．详细公式和推导保留在正文中．

已经迁移到注册表的术语，在术语表相应拼音分组中使用独立标记：

1
<!-- plw:glossary-entry differential-equation -->

构建从注册表生成该条目的名称、英文名、别名、释义和直接正文链接，不回写源文件．修改短释义应编辑注册表，不要同时保留手写的重复条目；尚未迁移的术语继续按原方式维护．

本地运行 uv run mkdocs build --clean 检查引用．重复 ID、未知 ID、缺少必填字段、无效目标文件或锚点、重复先修以及不支持的引用位置都会使构建失败，即使全站未启用严格模式．根据错误中的源页面、概念 ID 和目标修正内容；页面搬迁时更新注册表中的 target．

推荐页面骨架

一篇面向学习者的正文页，通常应包含以下八个部分：

  1. 本页要解决什么问题．
  2. 现象、疑问或反例引入．
  3. 核心对象与基本定义．
  4. 模型、定律、公式或推导．
  5. 典型例题．
  6. 常见误区与边界条件．
  7. 与前后章节的连接．
  8. 参考资料与延伸阅读．

并非每一页都要机械地写出八个二级标题，但读者应该能够在阅读中明确感受到这八类信息．

Why 推进写法

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

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

一个常见的四步写法是：

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

例题应该怎么写

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

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

例题推荐模板

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

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

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

常见写作问题

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

页面状态与元数据规范

页面的内容成熟度决定其在站内的导航权重与搜索引擎索引状态．页面元数据应在 frontmatter 中随内容一同维护．

页面三态生命周期

  1. 正式知识页 (status: review)：

    • 具备完整的物理背景引入、模型与公式推导、典型例题、适用边界与误区提示．
    • 默认允许搜索引擎 index, follow，自动进入 sitemap．
    • 必须在 frontmatter 中提供独立的 description，准确说明本页学什么、能解决什么问题．

  2. 起草完善页 (status: draft)：

    • 具备核心推导与基础知识骨架，能够自洽阅读，但例题、图解或拓展部分仍在补充．
    • 允许正常索引，在学科首页推荐学习流中可作为过渡章节．

  3. 规划建设页 (status: planned)：

    • 页面正文暂时仅为精确的 TO DO 或大纲骨架，尚未达到初学者自学标准．
    • 必须 显式标记为 noindex, follow，防止空内容被搜索引擎索引污染： 
      1
2
3
4
5
6
      ---
status: planned
meta:
  - name: robots
    content: noindex, follow
---
    • 在学科概览页中以「建设看板」展示，主学习路线中明确标注待建设节点，避免误导读者．

页面内容撰写完成并转为 stable 后，按下面的顺序发布：

  1. 将 frontmatter 中的 status 更新为 stable，并删除 robots 中的 noindex．
  2. 检查页面标题、先修依赖和正文结构．
  3. 补充独立的 description（自然中文，不夸大页面未包含的内容）．
  4. 执行构建并检查最终 HTML，确认自动进入 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．

发布前自检

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

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

章节补充说明

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

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

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

评论