Skip to content

DOCUMENTATION_STRUCTURE.md

Latest commit

 

History

History
123 lines (84 loc) · 3.64 KB

DOCUMENTATION_STRUCTURE.md

File metadata and controls

123 lines (84 loc) · 3.64 KB

Client SDK Go - 文档体系与分层说明

版本: v1.0.0

📋 文档定位总览

文档层次结构

client-sdk-js/
├── README.md                    # ⭐ 主入口：用户友好的 SDK 总览
├── docs/
│   ├── README.md               # 📚 文档中心：文档索引和导航
│   ├── DOCUMENTATION_STRUCTURE.md # 📋 本文档：文档体系说明
│   ├── DEVELOPER_GUIDE.md      # 📖 开发者指南：如何使用 SDK
│   ├── API_REFERENCE.md        # 📚 API 参考：接口详细说明
│   ├── BUSINESS_SCENARIOS.md  # 🎯 业务场景：如何实现业务场景
│   ├── SDK_ARCHITECTURE.md    # 🏗️ 架构设计：整体结构讨论
│   ├── APPLICATION_SCENARIOS_ANALYSIS.md  # 📊 场景分析：职责边界
│   ├── ARCHITECTURE_PLAN.md    # 📈 架构规划：未来演进
│   ├── SCENARIOS_VISUAL_GUIDE.md    # 📐 可视化指南：场景图表
│   └── WES_ERROR_SPEC_IMPLEMENTATION.md   # 🔧 错误规范实施
├── examples/
│   └── wesclient.md           # 📡 WESClient 使用示例
├── guides/
│   └── *.md                   # 🔧 业务服务指南
└── api/
    └── *.md                   # 📚 API 文档

🎯 核心文档的定位和职责

1. 主 README.md（/README.md）

定位：用户友好的 SDK 入口文档

职责：

  • ✅ 第一印象：让用户快速了解 SDK 是什么，为什么选择它
  • ✅ 30秒上手：提供最简单的安装和第一个应用示例
  • ✅ 核心能力展示：突出 SDK 的核心价值和能力
  • ✅ 架构概览：简洁的分层架构说明
  • ✅ 文档导航：按角色组织文档链接，指向文档中心

2. 文档中心（docs/README.md）

定位：文档索引和导航中心

职责：

  • ✅ 文档索引：列出所有文档及其定位
  • ✅ 按角色导航：为不同角色提供快速导航路径
  • ✅ 文档分类：按用户文档、设计文档、参考文档分类
  • ✅ 优先级标注：标注文档的重要程度（P0/P1/P2）
  • ✅ 使用建议：为不同场景提供文档使用建议

3. 开发者指南（docs/DEVELOPER_GUIDE.md）

定位：如何使用 JS/TS SDK 开发应用

职责：

  • ✅ 安装和环境：JS/TS SDK 安装与环境配置
  • ✅ 核心概念：客户端初始化、业务服务使用等
  • ✅ 开发模式：常见开发模式和最佳实践
  • ✅ 引用平台文档：平台概念请参考主仓库文档

4. API 参考（docs/API_REFERENCE.md）

定位：JS/TS SDK 接口详细说明

职责：

  • ✅ 完整 API 列表：所有 API 接口说明
  • ✅ 参数和返回值：详细的参数和返回值说明
  • ✅ 使用示例：每个 API 的使用示例
  • ✅ 引用平台文档：底层 API 规范请参考主仓库文档

🔗 与平台文档的关系

引用原则

  • ✅ 平台级文档（weisyn.git/docs）：系统级、平台级、规范级的权威说明
  • ✅ SDK 文档（client-sdk-js.git/docs）：JS/TS SDK 这一层的解读、对接与示例
  • ✅ 引用关系：SDK 文档引用平台文档，避免重复，保持一致性

📋 文档分类

用户文档（面向应用开发者）

  • 主 README
  • 开发者指南
  • API 参考
  • 业务场景实现指南

设计文档（面向架构师和贡献者）

  • SDK 内部架构
  • 应用场景分析
  • 架构规划
  • 场景可视化指南

参考文档（面向高级开发者）

  • WES Error Spec 实施
  • 文档体系说明

维护者: WES Core Team