Back to Details

documentation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation Management

文档管理

Overview

概述

This skill provides expertise for implementing and maintaining documentation in GitHub projects. Use when you need to create documentation structure, fix/update existing docs, or audit documentation health.
本技能提供在GitHub项目中实现和维护文档的专业能力，可在你需要创建文档结构、修复/更新现有文档或审核文档健康度时使用。

Context

适用场景

User wants to work with project documentation. They may:
  • Set up documentation for a new project or module
  • Fix or update existing documentation after code changes
  • Audit and repair documentation across a repository
All sub-skills accept a scope parameter to control how much of the project to work on.
用户需要处理项目文档，可能有以下需求：
  • 为新项目或新模块搭建文档体系
  • 在代码变更后修复或更新现有文档
  • 审核并修复整个仓库的文档问题
所有子技能都支持scope参数，用于控制处理项目文档的范围。

Sub-skills

子技能

CRITICAL: Load the appropriate sub-skill from 
sub-skills/
based on user intent.
  • initialize.md: Create documentation structure where none exists
  • maintain.md: Fix, update, or audit existing documentation
  • compress.md: Remediate legacy verbose documentation (should rarely be needed for new docs)
重要提示：请根据用户意图从
sub-skills/
目录中加载合适的子技能。
  • initialize.md: 从零创建文档结构
  • maintain.md: 修复、更新或审核现有文档
  • compress.md: 精简 legacy 冗余文档（新文档很少需要用到）

Scope Parameter

范围参数

ScopeDescriptionExample
repo
Entire repository"Fix all docs in this repo"
path=<dir>
Specific directory"Fix docs in src/components/"
doc=<file>
Single document"Fix this README.md"
depth=N
Limit recursion"Repo, 2 levels deep"
范围描述示例
repo
整个仓库"修复这个仓库里的所有文档"
path=<dir>
指定目录"修复src/components/目录下的文档"
doc=<file>
单个文档"修复这个README.md"
depth=N
限制递归深度"处理整个仓库，递归2层深度"

Process

流程

  1. Determine user intent (create, maintain, or compress)
  2. Determine scope (repo, path, or doc)
  3. Load appropriate sub-skill
  4. Follow sub-skill process with scope context
  5. Verification: Confirm documentation meets success criteria (no duplication, appropriate length, links work)
  1. 明确用户意图（创建、维护还是精简）
  2. 确定处理范围（仓库、目录或单个文档）
  3. 加载对应的子技能
  4. 结合范围上下文遵循子技能的处理流程
  5. 验证：确认文档符合成功标准（无重复内容、篇幅合理、链接可正常访问）

Resources

资源

  • resources/templates/: Templates for README, CONTRIBUTING, and CHANGELOG files
  • resources/templates/: 提供README、CONTRIBUTING、CHANGELOG文件的模板

Guidelines

指南

  • CRITICAL: You MUST use the templates provided by this skill
重要提示：你必须使用本技能提供的模板

Core Principles

核心原则

One fact, one place. Never duplicate information across layers. If something is documented in literate code comments, don't repeat it in the directory README. If it's in a directory README, don't repeat it in the root README. Link instead.
Conciseness first. Write tight documentation from the start. If you find yourself needing to compress docs, that's a sign of upstream problems. The compress sub-skill exists for legacy cleanup, not as a normal workflow.
Document why, not what. Code shows what happens. Documentation should explain why decisions were made, how pieces connect, and what's not obvious from reading the code.
一个事实仅存一处。绝对不要在不同分层中重复信息。如果某部分内容已经在清晰的代码注释中说明，就不要在目录README中重复；如果已经在目录README中说明，就不要在根README中重复，改用链接跳转即可。
简洁优先。从一开始就编写精简的文档，如果你发现需要精简文档，说明上游流程存在问题。精简子技能仅用于legacy内容清理，不是常规工作流。
记录原因而非内容。代码已经能说明实现了什么功能，文档应该解释决策的原因、各模块之间的关联，以及阅读代码无法直接得到的隐藏信息。

Anti-patterns to Avoid

需要避免的反模式

  • Same information in root README + directory README + code comments
  • README that restates what the code already shows
  • Documentation that requires regular "compression" passes
  • Directory READMEs that just list files (the filesystem already does that)
  • Verbose explanations when a link would suffice
  • 根README+目录README+代码注释中存在重复信息
  • README重复代码已经能说明的内容
  • 文档需要定期做"精简"处理
  • 目录README仅罗列文件（文件系统本身已经能实现这个功能）

Literate Code Comments

文学化代码注释

For small directories (1-2 files), well-written literate code comments may be sufficient. Skip the README if:
  • Files have proper literate headers (Title, Context, Decision)
  • The directory purpose is obvious from filenames
  • No complex interactions between files need explaining
A README adds value when:
  • Multiple files interact in non-obvious ways
  • External interface needs explanation beyond code
  • Directory contains subdirectories needing navigation
对于只有1-2个文件的小目录，如果代码注释写得足够清晰，可以不需要README，满足以下条件即可跳过README：
  • 文件有规范的说明头（标题、上下文、决策说明）
  • 从文件名就能明确目录的用途
  • 文件之间没有需要额外说明的复杂交互
README能产生价值的场景：
  • 多个文件之间存在不直观的交互逻辑
  • 需要对外提供代码之外的接口说明
  • 目录下包含多个子目录，需要导航指引

Layer Responsibilities

分层职责

LayerPurposeAudience
Root READMEProject overview, quick start, entry pointEveryone
Directory READMEHow files in this directory relate, local contextDevelopers working in this area
/docs folderCross-cutting topics that span multiple parts of the codebaseThose needing comprehensive understanding
Literate commentsWhy this code exists, decision rationaleFuture maintainers
Each layer answers different questions. If you're repeating yourself, you're in the wrong layer.
分层用途受众
根README项目概述、快速开始、入口指引所有相关人员
目录README说明当前目录下文件的关联、本地上下文在该模块工作的开发人员
/docs文件夹覆盖代码库多模块的跨领域主题需要全面理解项目的人员
代码注释代码存在的原因、决策逻辑后续的维护人员
每个分层负责回答不同的问题，如果你发现内容重复，说明你把内容放错了分层。

READMEs vs docs/ folder

README与docs/文件夹的区别

READMEs and docs/ serve fundamentally different purposes:
  • READMEs are vertical - They document a specific location (root project, a module, a directory). Each README belongs to exactly one place in the filesystem.
  • docs/ is horizontal - It documents topics that span multiple parts of the codebase. Architecture, authentication flows, data pipelines - these have no natural home in any single directory because they cross boundaries.
When to use each:
ContentLocationWhy
"How this module works"Directory READMESpecific to one location
"How auth, API, and DB interact"docs/architecture.mdSpans multiple modules
"Quick start for users"Root READMEEntry point for everyone
"Complete API reference"docs/api-reference.mdReference material, not entry point
"Tutorial: building a feature"docs/tutorials/Step-by-step guide touching many areas
Cross-references:
  • READMEs link to docs/ for cross-cutting topics: "See Architecture for how this module fits into the system"
  • docs/ links to READMEs for module-specific details: "For implementation details, see src/auth/README.md"
  • docs/index.md serves as navigation hub, linking to both other docs/ files and relevant READMEs
README和docs/的核心用途完全不同：
  • README是垂直的 - 它是对特定位置（根项目、某个模块、某个目录）的说明，每个README仅属于文件系统中的一个位置。
  • docs/是水平的 - 它用于记录跨代码库多模块的主题，比如架构、认证流程、数据管道，这些内容不属于任何单个目录，因为它们跨越了模块边界。
使用场景说明：
内容存放位置原因
"该模块的工作原理"目录README仅针对单个位置
"认证、API和数据库的交互逻辑"docs/architecture.md跨多个模块
"用户快速开始指南"根README面向所有人员的入口
"完整API参考"docs/api-reference.md参考材料，不是入口内容
"教程：开发一个新功能"docs/tutorials/分步指南，涉及多个模块
交叉引用规则：
  • README可以链接到docs/中的跨领域主题："查看架构文档了解该模块在整个系统中的定位"
  • docs/可以链接到README中的模块细节："实现细节请参考src/auth/README.md"
  • docs/index.md作为导航枢纽，同时链接到其他docs/文件和相关的README

Appendix

附录

Documentation Phases

文档阶段

PhaseStructureWhen to Use
1Single README.mdSimple projects, few files
2Multiple READMEs2+ modules with distinct purposes
3READMEs + /docsComplex architecture, multiple audiences
阶段结构使用场景
1单个README.md简单项目，文件数量少
2多个README有2个以上不同用途的模块
3README + /docs架构复杂，面向多类受众

Section-to-file graduation

内容从章节升级为独立文件的规则

Some documentation components start as sections within README and graduate to standalone files as the project grows. This avoids over-engineering docs for small projects while providing a clear upgrade path.
ComponentPhase 1 (inline)Phase 2+ (standalone)
ContributingSection in README under Developer GuideCONTRIBUTING.md
ChangelogSection in README under RoadmapCHANGELOG.md
Graduation triggers:
  • The section grows beyond ~30 lines
  • Multiple contributors need to reference it independently
  • The project is being published or has external users
部分文档内容一开始作为README的章节存在，随着项目增长可以升级为独立文件，既避免小项目的文档过度设计，也提供清晰的升级路径。
组件阶段1（内嵌在README中）阶段2+（独立文件）
贡献指南放在README的开发者指南章节下CONTRIBUTING.md
更新日志放在README的路线图章节下CHANGELOG.md
升级触发条件：
  • 章节内容超过30行
  • 多个贡献者需要独立引用该内容
  • 项目要对外发布或者有外部用户

Length Guidelines

长度规范

DocumentTargetMax
Root README200-300 lines500 lines
Directory README200-300 lines500 lines
/docs filesAs neededKeep focused
If a document exceeds these limits, it's probably:
  • Duplicating information from another layer
  • Covering too many topics (split it)
  • Too verbose (tighten the prose)
文档目标长度最大长度
根README200-300行500行
目录README200-300行500行
/docs下的文件按需而定保持内容聚焦
如果文档超过长度限制，很可能是以下问题：
  • 重复了其他分层的内容
  • 覆盖了太多主题（需要拆分）
  • 内容过于冗余（需要精简表述）

Success Criteria

成功标准

  • No information duplicated across layers
  • Each document serves a clear, distinct purpose
  • READMEs are concise entry points, not exhaustive references
  • READMEs follow templates provided
  • Small directories rely on literate comments when appropriate
  • All links work, no orphaned references
  • 各分层之间没有重复信息
  • 每个文档都有清晰明确的定位
  • README是精简的入口，不是详尽的参考文档
  • README遵循提供的模板
  • 小目录在合适的场景下优先使用代码注释
  • 所有链接可正常访问，没有孤立引用