文档放 Git 还是 MinDoc

背景

项目文档到底应该放在 Git 仓库里，还是放在 MinDoc 这类文档系统中，是一个很常见的问题。

如果只放 Git，优点是和代码同步，但阅读和搜索体验可能不如文档系统。

如果只放 MinDoc，优点是阅读方便，但容易和代码版本脱节。

因此，不建议简单二选一，而应该区分文档类型。

核心原则：

Git 仓库管版本
MinDoc 管阅读

Git 和 MinDoc 的定位

Git 仓库

Git 仓库适合保存和代码强绑定的文档。

它的优势是：

可以和代码一起提交
可以和分支一起演进
可以通过 PR / MR review
可以和 tag、commit、release 对应
可以追溯某个时间点的真实状态
不容易出现“代码一套、文档一套”

Git 更适合回答：

这个版本的系统到底是怎么实现的？
这个功能上线时对应的文档是什么？
这个表结构变更和哪个功能有关？
这个决策是在什么时候引入的？

MinDoc

MinDoc 适合保存知识库型、阅读型、长期沉淀型文档。

它的优势是：

阅读方便
分类清晰
搜索方便
适合跨项目沉淀
适合业务知识和技术经验整理
对非研发人员更友好

MinDoc 更适合回答：

这个业务概念是什么？
这个技术方案怎么理解？
这个规范怎么执行？
这个项目整体怎么介绍？
这个问题以前怎么排查？

推荐原则

1. 和代码强绑定的文档优先放 Git

以下文档建议优先放项目仓库：

README
启动说明
本地开发说明
Feature 功能档案
Decision 决策文档
Changelog
数据库 migration 说明
SQL 脚本
接口实现说明
项目专属规范
部署脚本说明
和版本强相关的上线说明

原因是这些文档需要和代码版本一起变化。

例如：

docs/features/2026-06-11-etf-fund-flow-rank.md
docs/decisions/2026-06-11-etf-rank-use-independent-table.md
docs/changelog/2026-06.md
docs/sql/2026-06-11-etf-share-change-rank.sql

2. 知识库型文档优先放 MinDoc

以下文档建议优先放 MinDoc：

业务知识
技术知识
通用代码规范
通用架构经验
运维经验
问题排查手册
复盘总结
跨项目最佳实践
学习笔记
团队研发流程
文档体系说明

例如：

10-研发管理 / 文档体系 / PRD / Feature / Decision 的关系
20-Java技术 / 代码规范 / Req Resp 命名规范
30-运维部署 / Docker 镜像优化
40-业务知识库 / ETF / ETF 份额变化

3. 重要文档可以两边都有，但必须明确源头

有些文档既需要版本管理，又需要良好的阅读体验，可以两边都有。

但必须明确：

哪一边是源头？
哪一边是展示？

推荐方式：

Git 仓库是源头
MinDoc 是展示

也就是说，先在 Git 仓库维护原始 Markdown，然后同步或复制到 MinDoc 中阅读。

这样可以避免：

Git 里一份
MinDoc 里一份
两边内容不一致
没人知道哪个是真的

文档类型建议

文档类型	Git	MinDoc	说明
README	必须	可同步	项目入口
本地启动说明	必须	可同步	和项目版本强相关
Feature 功能档案	必须	可同步	功能历史，和代码强绑定
Decision 决策文档	必须	可同步	设计原因，和代码强绑定
Changelog	必须	可同步	版本历史
SQL / migration	必须	不建议作为源头	真实结构必须在代码仓库
项目专属规范	必须	可同步	和项目约束相关
通用 Java 规范	可放	推荐	跨项目复用
业务知识	可放	推荐	说明 what，扩展知识面
运维排查手册	可放	推荐	跨项目经验沉淀
研发流程规范	可放	推荐	例如文档体系、分支规范、CR 规范
项目总览	可放	推荐	MinDoc 阅读体验更好

推荐目录：项目仓库

项目仓库中可以使用：

docs/
  README.md

  features/
    2026-06-11-etf-fund-flow-rank.md

  decisions/
    2026-06-11-etf-rank-use-independent-table.md

  changelog/
    2026-06.md

  sql/
    2026-06-11-etf-share-change-rank.sql

  standards/
    project-module-standard.md
    api-path-standard.md

  plans/
    module-refactor-plan.md

其中：

features/   记录功能最终怎么实现
decisions/  记录为什么这样设计
changelog/  记录什么时候做了什么
sql/        保存数据库脚本或说明
standards/  保存项目专属规范
plans/      保存项目计划或重构方案

推荐目录：MinDoc

MinDoc 中可以使用：

10-研发管理
  ├── 文档体系
  │   ├── PRD / Feature / Decision 的关系
  │   ├── Feature 功能档案模板
  │   ├── Decision 决策文档模板
  │   └── 文档放 Git 还是 MinDoc
  ├── 开发流程
  └── 项目复盘

20-Java技术
  ├── 代码规范
  ├── Spring Boot
  ├── Quarkus
  └── 单元测试

30-运维部署
  ├── Docker
  ├── Nginx
  ├── EFK
  └── Linux

40-业务知识库
  ├── ETF
  ├── 股票
  └── 财经日历

50-项目档案
  ├── ETF系统
  ├── MinDoc
  └── 其他项目

其中：

10-研发管理：怎么维护项目
20-Java技术：怎么写代码
30-运维部署：怎么部署和排查
40-业务知识库：业务是什么
50-项目档案：具体项目发生过什么

判断标准

遇到一篇文档时，可以问一句：

这个文档是否需要跟着代码版本一起走？

如果答案是“是”，优先放 Git。

例如：

这个接口怎么实现
这个功能怎么上线
这个表为什么新增
这个字段和哪个版本有关
这个功能最终做成什么样

再问一句：

这个文档是否是跨项目通用知识，主要用于阅读和沉淀？

如果答案是“是”，优先放 MinDoc。

例如：

ETF 是什么
Java 代码规范
Docker 镜像优化经验
日志系统搭建手册
PRD Feature Decision 的关系

同步方式

如果一篇文档既放 Git，也放 MinDoc，建议在 MinDoc 顶部注明来源。

示例：

来源：项目仓库 docs/features/2026-06-11-etf-fund-flow-rank.md
说明：Git 仓库为原始版本，MinDoc 仅用于阅读。

或者在 Git 文档顶部注明：

本文档会同步到 MinDoc：50-项目档案 / ETF系统 / 功能历史 / ETF 资金异动榜

常见错误

错误一：所有文档只放 MinDoc

问题：

和代码版本脱节
不经过代码 review
很难知道某个版本对应哪份文档
功能变了但文档没变

错误二：所有文档只放 Git

问题：

阅读体验差
搜索和分类不方便
业务文档和知识沉淀不适合非研发阅读
跨项目知识复用困难

错误三：两边都放，但没有源头

问题：

Git 一份，MinDoc 一份
两边内容逐渐不一致
后续没人知道该信哪一份

正确做法是明确：

Git 是源头，MinDoc 是展示。

或者对某些知识库文档明确：

MinDoc 是源头，项目中只放链接。

最终建议

对于个人项目或小团队，推荐这样做：

代码相关文档：先放项目 docs/
知识库型文档：放 MinDoc
重要 docs：可同步到 MinDoc 展示

一句话总结：

Git 仓库管版本，MinDoc 管阅读。

不要把 MinDoc 当成代码相关文档的唯一存储，也不要把 Git 当成所有知识库的唯一入口。

作者：张三创建时间：2026-06-11 10:26
最后编辑：张三更新时间：2026-06-11 10:35

上一篇： Decision 决策文档模板
下一篇：项目复盘