跳到主要内容

文档写作规范

本文参考 MDN 文档写作规范，结合本知识库场景做了精简。目标是：清晰、简洁、一致，让读者快速判断「这篇有没有我要的答案」。

通用原则​

考虑读者​

  • 先想清楚读者是谁：入门、进阶还是复盘笔记。
  • 同一领域内保持难度一致；跨领域链接到导览页，不要在一篇里堆太多无关背景。

写作的「3C」​

准则说明
清晰短句、一句一意；新术语先定义；多用主动语态。
简洁只写读者需要的信息；细节放到子篇，导览页只做索引。
一致同一概念全站用词统一；标题层级与文件名规则见 整理原则。

开篇段落（很重要）​

标题之前用 1～3 段 说明：

  1. 本文讲什么、解决什么问题
  2. 读完后读者能做什么或理解什么
  3. （可选）需要先读哪些前置文章
备注

反例（过短）：「本文介绍 Swift 并发。」—— 读者不知道范围与收获。
反例（过长）：在开头堆砌大量 API 细节—— 应放到正文分节。

示例与代码​

  • 每个重要概念至少配 一个可运行的例子 或真实场景。
  • 代码块加 title 标明语言/文件名；行内代码用 `符号`。
  • 边缘情况单独一小节，不要埋在长段落里。

包容性用语​

避免 master/slave、黑白名单等表述；性别无关时用「用户」「其」或改写为无主语句。

SEO（可选）​

  • 标题与首段包含读者可能搜索的关键词（自然即可，不堆砌）。
  • 使用描述性链接文字，避免「点击这里」。

页面结构（MDN 风格）​

推荐顺序：

  1. 导言（无 ## 标题前的段落）
  2. ## 二级标题 — 主要章节
  3. ### 三级标题 — 小节
  4. 参考 / 延伸阅读 — 外链与相关站内文

提示框（Admonition）​

本站支持 Docusaurus 提示框，写法类似 MDN 的 Note / Warning：

:::note
补充说明，不打断主流程。
:::

:::tip
更省力的做法或经验技巧。
:::

:::warning
投资、健康、法律等需谨慎的说明。
:::

:::info
背景知识或延伸阅读提示。
:::
提示

提示框不宜过多；一篇里 2～4 个通常足够。

与本站其他指南的关系​

文档用途
整理原则目录、命名、协作
目录大纲文件树与侧栏
广告与变现AdSense 配置说明

参考​