跳到主要内容

阅读指南：Blog 和文档应该怎么读

· 阅读需 5 分钟

这个站点同时保留 Blog 和文档区：Blog 用来承载一个专题、一段排查过程或一个范围性问题；文档区则拆成原子化页面，说明某一个具体、清晰、可复用的事情。

Blog 和文档的区别​

Blog：围绕专题解决一类问题​

Blog 更适合记录“范围性问题”。它不一定只回答一个命令怎么写，而是把一个主题里的背景、约束、尝试、取舍和结论串起来。

比如当前这类“自动化部署链路搭建”内容，就不仅是 Jenkins 的某个配置项，而是会同时涉及：

  1. 代码仓库触发 Jenkins 任务。
  2. Jenkins 拉取代码并执行构建脚本。
  3. 构建环境通过代理访问外部依赖源。
  4. 构建产物打包成 Docker 镜像。
  5. 镜像推送到 Docker 仓库。
  6. 目标服务器拉取镜像并重启服务。

这些内容放在 Blog 里更自然，因为读者通常需要先理解“整条链路怎么协作”，再定位自己要落地或排查的环节。

Blog 还适合记录：

  • 一个专题的完整配置过程，例如 Jenkins 的一系列配置和使用。
  • 一个 bug 的发现、定位、尝试和最终解决过程。
  • 某个方案为什么这样设计，以及中间放弃过哪些做法。
  • 多个工具组合使用时的上下文，例如 Jenkins、Docker、代理、仓库和服务器部署之间的关系。

文档：回答一个原子问题​

文档区更适合放“原子化答案”。每一篇文档尽量只说明一个具体、清晰、边界明确的事情，读者可以直接搜索、打开、照做或引用。

例如：

  • Docker 如何安装。
  • 如何用 Docker 部署 MySQL。
  • 某个 Java 报错的原因和处理方式。
  • 某个 Nebula 模块的配置项、接口、DDL 或使用说明。

如果一篇内容可以被命名成“如何做某一件具体的事”，并且不依赖很长的前因后果，它通常更适合放在文档区。

当前文档站是怎么设计的​

这个站点的阅读入口按内容类型拆开：

  • 专题：对应 Blog，用来阅读跨多个工具、配置和系统的大型问题处理过程。
  • 教程：按 Linux、Windows、macOS、Docker、Kubernetes、CI/CD、Java、数据库、网络等场景组织，适合找“怎么做”。
  • 踩坑：同样按技术场景分类，适合找“为什么出错、怎么修”。
  • Nebula：按模块组织框架能力，每个模块下再拆成概览、业务能力、配置、DDL、接口、设计实现和使用指南。
  • 搜索：站点会索引文档、Blog 和页面，适合在不知道分类时直接检索关键字。

文档区的侧边栏采用自动生成方式：新增内容时，优先把文档放进对应目录；目录页使用 index.md；分类元数据通过 _category_.json 维护名称、顺序和可点击入口。这样可以让目录结构、页面 URL 和侧边栏尽量保持稳定。

推荐阅读方式​

先判断自己在找什么​

如果你想了解一个专题的完整背景，先看 Blog。例如自动化部署相关内容，就应该先从专题文章理解 Jenkins、脚本、代理、Docker 仓库和服务器部署之间的关系。

如果你只想完成一个明确动作，直接去文档区。例如“Docker 安装”“Docker 部署 MySQL”“某个报错怎么修”这类问题，不需要先读一篇长文。

再选择入口​

  • 找操作步骤：优先看 教程。
  • 找故障处理：优先看 踩坑。
  • 找框架模块说明：优先看 Nebula。
  • 找完整方案、排查过程、设计思路：优先看 专题。
  • 不确定放在哪里：直接用搜索。

最后回到原子文档落地​

Blog 通常负责把问题讲完整，但真正落地时，仍然应该回到原子文档确认具体命令、配置项和注意事项。也就是说：

  1. 用 Blog 建立上下文。
  2. 用文档执行具体步骤。
  3. 遇到报错时到踩坑区检索。
  4. 如果问题跨多个环节，再回到 Blog 看完整链路。

后续内容应该怎么写​

后续新增内容时，可以按下面的规则判断放在哪里：

  • 放 Blog：一个专题、一条链路、一次完整排查、一个 bug 的解决过程、一个方案的思考过程。
  • 放文档：一个明确动作、一个清晰配置、一个具体命令、一个可独立复用的问题答案。

例如 Jenkins 的一系列配置和使用，可以作为 Blog 记录完整部署链路；而“Docker 安装”“Docker 部署 MySQL”这类内容，则应该拆成独立文档，方便搜索和复用。

这样的分工可以让 Blog 保留真实的问题现场，也让文档区保持短、准、可检索。