跳到主要内容

DatomsDBS 文档组织策略

注意：这是内部讨论文档，不应在公开文档站点中显示

🤔 问题分析​

当前我们面临一个常见的开源项目问题：是否将文档与代码分离？

📊 方案对比​

方案一：当前方案（代码+文档同仓库）​

仓库结构：

datomsDBS/
├── src/                    # 源代码
├── docs/                   # 完整技术文档
├── README.md               # 项目介绍
├── _config.yml             # Jekyll配置
└── index.md                # 文档首页

GitHub Pages URL： https://username.github.io/datomsDBS/

优点：

  • ✅ 文档与代码版本完全同步
  • ✅ 开发者友好，容易维护
  • ✅ 符合开源项目标准实践
  • ✅ 单一仓库，管理简单

缺点：

  • ❌ 非技术用户可能被代码文件困惑
  • ❌ URL 不够专业（包含仓库名）
  • ❌ 混合内容，不够专注

方案二：独立文档仓库​

仓库结构：

datomsDBS/                  # 主项目
├── src/
├── README.md               # 基础说明
└── docs/ -> 链接到文档站点

datomsDBS-docs/             # 独立文档仓库
├── docs/
├── _config.yml
└── index.md

GitHub Pages URL： https://username.github.io/datomsDBS-docs/

优点：

  • ✅ 专业的文档站点
  • ✅ 可使用自定义域名
  • ✅ 用户体验更好
  • ✅ 独立权限管理

缺点：

  • ❌ 维护两个仓库
  • ❌ 版本同步复杂
  • ❌ 开发者需要记住两个地址

方案三：混合方案（推荐）​

仓库结构：

datomsDBS/                  # 主项目（保持当前结构）
├── src/
├── docs/                   # 完整文档
├── README.md               # 开发者文档
└── _config.yml

docs.datomsdbs.com          # 自定义域名指向
-> https://username.github.io/datomsDBS/

实施步骤：

  1. 保持当前文档结构
  2. 添加自定义域名
  3. 优化用户引导

🎯 推荐方案：混合策略​

为什么选择混合方案？​

  1. 保持当前优势

    • 文档与代码同步
    • 开发者友好
    • 维护简单

  2. 提升用户体验

    • 使用自定义域名
    • 专业的访问入口
    • 清晰的用户引导

  3. 平衡各方需求

    • 开发者：在代码库中直接维护文档
    • 用户：通过专业域名访问文档
    • 管理者：只需维护一个仓库

实施计划​

阶段一：优化当前方案​

  1. 改进文档首页

    • 突出产品特性
    • 弱化技术细节
    • 增加用户导航

  2. 添加用户类型导航

    ## 👥 选择您的角色

    ### 🔧 系统管理员
    - [快速部署指南](docs/deployment_guide.md)
    - [配置说明](docs/technical/#配置指南)

    ### 👨‍💻 开发者
    - [技术文档](docs/technical/)
    - [API 参考](docs/api/)
    - [GitHub 仓库](https://github.com/username/datomsDBS)

    ### 📊 最终用户
    - [使用指南](docs/user-guide/)
    - [常见问题](docs/faq/)

阶段二：自定义域名（可选）​

  1. 申请域名

    • docs.datomsdbs.com
    • datomsdbs.github.io

  2. 配置 CNAME

    echo "docs.datomsdbs.com" > CNAME
    git add CNAME
    git commit -m "Add custom domain"
    git push

  3. DNS 配置

    Type: CNAME
    Name: docs
    Value: username.github.io

阶段三：内容优化​

  1. 分层文档结构

    docs/
    ├── user-guide/           # 最终用户指南
    ├── admin-guide/          # 管理员指南
    ├── developer-guide/      # 开发者指南
    ├── api-reference/        # API 参考
    └── technical/            # 技术细节

  2. 角色导向的着陆页

    • 根据用户类型提供不同的入口
    • 隐藏不相关的技术细节

实际效果预期​

开发者视角：

  • 克隆仓库，文档就在 docs/ 目录
  • 修改代码时可以同步更新文档
  • Pull Request 包含代码和文档更改

用户视角：

  • 访问 docs.datomsdbs.com（或当前GitHub Pages URL）
  • 看到产品介绍和使用指南
  • 不会被源代码文件困扰

管理视角：

  • 只需维护一个仓库
  • 文档自动与代码版本同步
  • 简单的部署和更新流程

🚀 立即行动​

保持当前方案的理由​

  1. DatomsDBS 是技术产品

    • 主要用户是开发者和系统管理员
    • 技术文档是核心需求
    • 代码和文档的一致性很重要

  2. 当前设置已经很专业

    • Jekyll + GitHub Pages 是行业标准
    • 响应式设计，移动设备友好
    • 自动部署，维护成本低

  3. 可以渐进式改进

    • 不需要重构，风险低
    • 可以逐步优化用户体验
    • 后续可以考虑添加自定义域名

下一步建议​

  1. 完善当前文档站点

    # 保持当前设置，继续优化内容
    git add .
    git commit -m "Optimize documentation for different user types"
    git push origin main

  2. 监控用户反馈

    • 观察文档站点的访问模式
    • 收集用户使用反馈
    • 根据实际需求调整策略

  3. 考虑未来扩展

    • 如果用户群体扩大，可以考虑独立文档站点
    • 如果需要多语言支持，可能需要更复杂的结构
    • 商业化后可能需要独立的品牌域名

📝 结论​

建议继续使用当前方案，原因如下：

  1. ✅ 适合DatomsDBS的技术产品定位
  2. ✅ 符合开源项目最佳实践
  3. ✅ 维护成本低，开发效率高
  4. ✅ 已经具备专业文档站点的功能
  5. ✅ 可以根据需要渐进式改进

如果将来需要独立文档站点，可以很容易地迁移当前的Jekyll设置到新仓库。

选择最适合当前阶段的方案，保持灵活性以应对未来需求的变化。 🎯

编辑此页
最后由 jerry zhang 于 更新