Skip to content

文档规范

一份好的技术文档应该让读者能够独立、高效地获取信息。以下是我们对文档质量的基本要求。

1. 文字表述

  • 清晰优先：用简洁直白的语言，避免过度修饰。先讲"是什么"，再讲"为什么"，最后讲"怎么做"。
  • 概念明确：首次出现的术语或缩写需给出全称或解释。例如："HAL（Hardware Abstraction Layer，硬件抽象层）"。
  • 分层架构：长文档应有清晰的标题层级（# → ## → ###），让读者能快速定位所需内容。

2. 内容组织

  • 先总后分：开头用一两句话概述本文档的目的和适用人群。
  • 有目录：较长的文档（超过 3 个二级标题）建议在开头放一个目录。
  • 善用表格：对比型信息（如不同模式的差异、优缺点）用表格呈现。
  • 配上代码：涉及编程的内容必须附上可运行的代码示例。

3. 实操性

  • 涉及工具/环境配置的文档，必须给出可逐条执行的步骤。
  • 常见错误和解决方案应当单独列出。

4. 署名要求

每份文档末尾必须包含署名块，格式如下：

> **作者**: [昵称](GitHub链接) | **修改日期**: YYYY-MM-DD

如有后续修改者，追加一行即可：

> **作者**: [Qing](https://github.com/ZhangChuqing) | **修改日期**: 2026-07-18
> **修改**: [李四](https://github.com/lisi) | **修改日期**: 2026-08-01 | 补充了CAN通信部分

署名使用 > 引用格式，灰色低调但可追溯，方便后来者遇到问题时联系原作者。

5. 插图与示意图

  • 示意图一律用 SVG，不要用等宽字符拼 ASCII 图：字符画在不同设备/字号下会错位，改起来也痛苦。
  • 文件放 docs/assets/diagrams/（私有站的放私有仓库的 docs/assets/diagrams/），命名用小写英文短横线， 如 arch-overview.svg。
  • 引用写法（前后各留一个空行，否则 Markdown 会把后面的列表吞进 HTML 块）：
<figure class="diagram">
  <img src="/assets/diagrams/arch-overview.svg" alt="一句话描述这张图">
  <figcaption>图 1：这张图说明了什么</figcaption>
</figure>
  • 公开站页面里的图用 /assets/diagrams/xxx.svg；私有站页面要写 /_private/assets/diagrams/xxx.svg—— 私有页面的相对路径指不到公开站，必须用站点绝对路径。
  • 画 SVG 的几条约定：
  • 根元素写 viewBox（自适应缩放）；
  • 根元素 font-family 用系统字体栈 system-ui, 'Microsoft YaHei', sans-serif，中文才不会被换掉；
  • 图自带浅色卡片底（#f7f9fc + 圆角描边），这样深色主题下也看得清；
  • 加 role="img" 与 <title>/<desc>，便于读屏与搜索；
  • 主色沿用站点的 #4051b5，强调色用 #7b6bd6 / #e2b862。
  • 样式（图片自适应宽度、图注字号）已经写在 docs/assets/caf.css 的「SVG 图表」一节里，直接用即可。