Back to Details

docs-generator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Workflow

工作流程

0. Create Feature Branch

0. 创建功能分支

Before making any changes:
  1. Check the current branch - if already on a feature branch for this task, skip
  2. Check the repo for branch naming conventions (e.g., 
    feat/
    , 
    feature/
    , etc.)
  3. Create and switch to a new branch following the repo's convention, or fallback to: 
    feat/docs-generator
在进行任何更改之前：
  1. 检查当前分支——如果已经处于该任务对应的功能分支，可跳过此步骤
  2. 查看仓库的分支命名规范（例如
    feat/
    、
    feature/
    等）
  3. 遵循仓库规范创建并切换到新分支，若无规范则默认使用：
    feat/docs-generator

1. Analyze Project

1. 分析项目

Identify:
  • Project type: Library, API, web app, CLI, microservices
  • Architecture: Monorepo, multi-package, single module
  • User personas: End users, developers, operators
确定：
  • 项目类型：库、API、Web应用、CLI、微服务
  • 架构：单仓多包（Monorepo）、多包、单模块
  • 用户角色：终端用户、开发者、运维人员

2. Restructure Documentation

2. 重构文档结构

Root README.md - Streamline as entry point:
  • Project overview and purpose
  • Quickstart (install + first use)
  • Modules/components summary with links
  • License and contacts
Component READMEs - Add per module/package/service:
  • Purpose and responsibilities
  • Setup instructions
  • Testing commands
Centralize in 
docs/
 - Organize by category (select applicable):
docs/
├── architecture.md      # System design, diagrams
├── api-reference.md     # Endpoints, authentication
├── database.md          # Schema, migrations
├── deployment.md        # Production setup
├── development.md       # Local setup, contribution
├── troubleshooting.md   # Common issues
└── user-guide.md        # End-user documentation
根目录README.md——精简为入口文档：
  • 项目概述与用途
  • 快速入门（安装+首次使用）
  • 模块/组件摘要及链接
  • 许可证与联系方式
组件级README——为每个模块/包/服务添加：
  • 用途与职责
  • 安装配置说明
  • 测试命令
集中存放至
docs/
目录——按类别组织（选择适用的类别）：
docs/
├── architecture.md      # 系统设计、图表
├── api-reference.md     # 接口、认证方式
├── database.md          # 数据库 schema、迁移
├── deployment.md        # 生产环境部署
├── development.md       # 本地开发环境搭建、贡献指南
├── troubleshooting.md   # 常见问题排查
└── user-guide.md        # 终端用户指南

3. Create Diagrams

3. 创建图表

Use Mermaid for all visual documentation:
  • Architecture diagrams
  • Data flow diagrams
  • Database schemas
所有可视化文档使用Mermaid创建：
  • 架构图
  • 数据流图
  • 数据库 schema 图

Guidelines

指南

  • Keep docs concise and scannable
  • Adapt structure to project type (not all categories apply)
  • Maintain cross-references between related docs
  • Remove redundant or outdated content
  • 文档简洁易读，便于快速浏览
  • 根据项目类型调整结构（无需套用所有类别）
  • 保持相关文档间的交叉引用
  • 删除冗余或过时内容