⚡

管理文档Skill managing-docs

管理文档技能是专门针对软件项目文档的组织、结构化和管理而设计的。它在用户需要设置项目文档、配置文档工具、询问文档最佳实践或重构现有文档时自动触发。此技能覆盖了文档架构模式、文档类型、文档工具设置、文档标准、版本化文档策略以及文档迁移和自动化策略。

文档管理 1 次安装 6 次浏览 更新于 3/2/2026

管理文档技能

您是组织、结构化和管理软件项目文档的专家。

何时激活此技能

此技能在以下情况下自动触发：

  • 用户询问文档结构或组织
  • 用户希望为项目设置文档
  • 用户需要配置文档工具（Sphinx、MkDocs等）
  • 用户询问文档最佳实践组织
  • 用户希望重构现有文档

文档架构模式

模式1：简单项目（README中心）

最适合：小型项目、库、单一用途工具

项目/
├── README.md           # 主要文档
├── CONTRIBUTING.md     # 贡献指南
├── CHANGELOG.md        # 版本历史
├── LICENSE             # 许可证文件
└── docs/
    └── api.md          # API参考（如果需要）

模式2：标准项目（文档目录）

最适合：中型项目、具有多个功能的应用程序

项目/
├── README.md           # 概览和快速开始
├── CONTRIBUTING.md
├── CHANGELOG.md
├── LICENSE
└── docs/
    ├── index.md        # 文档主页
    ├── getting-started.md
    ├── installation.md
    ├── configuration.md
    ├── usage/
    │   ├── basic.md
    │   └── advanced.md
    ├── api/
    │   ├── index.md
    │   └── [模块].md
    ├── guides/
    │   └── [主题].md
    └── troubleshooting.md

模式3：大型项目（完整文档网站）

最适合：大型项目、框架、平台

项目/
├── README.md
├── CONTRIBUTING.md
├── CHANGELOG.md
├── LICENSE
└── docs/
    ├── mkdocs.yml          # 文档网站配置
    ├── index.md
    ├── getting-started/
    │   ├── index.md
    │   ├── installation.md
    │   ├── quick-start.md
    │   └── first-project.md
    ├── guides/
    │   ├── index.md
    │   └── [主题]/
    │       └── index.md
    ├── reference/
    │   ├── index.md
    │   ├── api/
    │   ├── cli/
    │   └── configuration/
    ├── tutorials/
    │   └── [教程]/
    ├── concepts/
    │   └── [概念].md
    ├── examples/
    │   └── [示例]/
    └── contributing/
        ├── index.md
        ├── development.md
        └── style-guide.md

模式4：Monorepo文档

最适合：具有多个包的Monorepos

monorepo/
├── README.md               # Monorepo概览
├── docs/
│   ├── index.md           # 整体文档
│   ├── architecture.md
│   └── packages.md
└── packages/
    ├── package-a/
    │   ├── README.md      # 包特定文档
    │   └── docs/
    └── package-b/
        ├── README.md
        └── docs/

文档类型

1. 参考文档

  • API文档
  • 配置选项
  • CLI命令
  • 数据类型和模式

特点：

  • 全面且详尽
  • 按字母顺序或模块组织
  • 尽可能自动生成
  • 从教程和指南中链接

2. 概念性文档

  • 架构概览
  • 设计决策
  • 内部工作原理
  • 理论背景

特点：

  • 解释"为什么"
  • 提供上下文
  • 有帮助时使用图表
  • 链接到参考文档

3. 程序文档（如何指南）

  • 逐步指导
  • 任务导向内容
  • 特定目标
  • 常见工作流

特点：

  • 编号步骤
  • 清晰的先决条件
  • 预期结果
  • 故障排除提示

4. 教程文档

  • 学习导向内容
  • 动手练习
  • 逐步增加复杂性
  • 完整示例

特点：

  • 初学者友好
  • 自包含
  • 包含工作代码
  • 在前一步的基础上构建

文档工具设置

MkDocs（Python项目）

安装：

pip install mkdocs mkdocs-material

基本mkdocs.yml：

site_name: 项目名称
theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections
    - search.highlight

nav:
  - 首页：index.md
  - 快速开始：
    - 安装：getting-started/installation.md
    - 快速开始：getting-started/quick-start.md
  - 指南：
    - guides/index.md
  - API参考：
    - reference/index.md

plugins:
  - search
  - autorefs

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.superfences
  - admonition
  - toc:
      permalink: true

命令：

mkdocs serve      # 本地开发服务器
mkdocs build      # 构建静态网站
mkdocs gh-deploy  # 部署到GitHub Pages

Docusaurus（JavaScript项目）

安装：

npx create-docusaurus@latest docs classic

关键配置（docusaurus.config.js）：

module.exports = {
  title: '项目名称',
  tagline: '项目口号',
  url: 'https://your-domain.com',
  baseUrl: '/',
  themeConfig: {
    navbar: {
      title: '项目',
      items: [
        { to: '/docs/intro', label: '文档', position: 'left' },
        { to: '/blog', label: '博客', position: 'left' },
      ],
    },
  },
};

Sphinx（Python API文档）

安装：

pip install sphinx sphinx-rtd-theme
sphinx-quickstart docs

conf.py设置：

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.viewcode',
]

html_theme = 'sphinx_rtd_theme'

# Napoleon设置为Google风格的文档字符串
napoleon_google_docstring = True
napoleon_numpy_docstring = False

TypeDoc（TypeScript项目）

安装：

npm install typedoc --save-dev

typedoc.json：

{
  "entryPoints": ["src/index.ts"],
  "out": "docs/api",
  "exclude": ["**/*.test.ts"],
  "excludePrivate": true,
  "includeVersion": true
}

文档标准

文件命名约定

✓ getting-started.md      # 小写连字符
✓ api-reference.md        # 清晰描述性
✓ installation.md         # 单字尽可能

✗ GettingStarted.md       # 无PascalCase
✗ getting_started.md      # 无下划线
✗ GETTING-STARTED.md      # 无全大写（特殊文件除外）

特殊文件

README.md       # 项目概览（必需）
CONTRIBUTING.md # 贡献指南
CHANGELOG.md    # 版本历史
LICENSE         # 许可证文本
CODE_OF_CONDUCT.md # 社区标准
SECURITY.md     # 安全政策

文档结构检查表

项目根目录：

  • [ ] README.md带有概览和快速开始
  • [ ] CONTRIBUTING.md带有贡献指南
  • [ ] CHANGELOG.md带有版本历史
  • [ ] LICENSE文件

文档目录：

  • [ ] 清晰的导航结构
  • [ ] 快速入门指南
  • [ ] API/参考文档
  • [ ] 示例目录
  • [ ] 搜索功能（如果使用文档网站）

单个文档：

  • [ ] 清晰的标题
  • [ ] 目录（对于长文档）
  • [ ] 逻辑部分组织
  • [ ] 相关代码示例
  • [ ] 链接到相关内容

版本化文档

对于具有多个版本的项目：

策略1：基于分支

docs/
├── latest/           # 当前版本的符号链接
├── v2.0/
├── v1.5/
└── v1.0/

策略2：Docusaurus版本控制

npm run docusaurus docs:version 1.0

策略3：ReadTheDocs版本控制

基于git标签的自动版本切换。

迁移策略

迁移到文档目录

  1. 创建docs/目录结构
  2. 将内联文档移动到适当的文件
  3. 更新链接和引用
  4. 添加导航配置
  5. 设置文档站点生成器（如果使用）
  6. 重定向旧文档URL

合并文档

  1. 审核所有现有文档
  2. 识别重复和冲突
  3. 创建规范版本
  4. 删除或重定向重复
  5. 更新所有内部链接

自动化

GitHub Actions用于文档

name: 部署文档

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.x'
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

预提交钩子用于文档

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/igorshubovych/markdownlint-cli
    rev: v0.37.0
    hooks:
      - id: markdownlint
        args: ['--fix']

集成

此技能与以下技能一起使用：

  • 分析文档技能，用于评估当前文档状态
  • 编写文档技能，用于创建文档内容
  • 文档分析器代理，用于全面的文档项目