---
id: gh-doc-maintenance
name: "doc-maintenance"
url: https://skills.yangsir.net/skill/gh-doc-maintenance
author: getpaperclipai
domain: writing
tags: ["documentation", "drift-detection", "release-notes", "technical-writing", "maintenance"]
install_count: 1400
rating: 4.30 (120 reviews)
github: https://github.com/getpaperclipai/paperclip/tree/master/packages/skills-catalog/catalog/bundled/docs/doc-maintenance
---

# doc-maintenance

> 此技能自动检测代码变更与文档间的差异，精准更新受影响的页面、示例和发行说明，避免不必要的重写。适用于API文档、CLI参考、配置文件指南等场景，大幅降低人工审查和手动同步的工作量。

**Stats**: 1,400 installs · 4.3/5 (120 reviews)

## Before / After 对比

### 手动文档维护 vs 使用此技能

**Before**:

在没有这个技能之前，开发者需要手动比对代码提交记录和现有文档，逐页查找过时内容，更新时还需注意不引入格式混乱。每周平均耗费约4小时，且容易遗漏某些页面或示例，导致文档与实际行为不符。

**After**:

该Skill自动分析代码变更范围，精准定位需要更新的文档页、代码块和版本说明，仅修改需改动的行。用户只需审查建议的变更，每周维护时间降至0.5小时以内，文档与代码始终同步。

| Metric | Before | After | Change |
|---|---|---|---|
| 每周文档维护时间 | 240分钟 | 30分钟 | -87.5% |

## Readme

# Doc Maintenance

Keep the documentation honest with minimum churn. The goal is alignment between docs and behavior, not stylistic rewrites or cosmetic re-organization. Reviewers should be able to read a diff and see "this updates docs to match recent behavior changes".

## When to use

- A PR or recent set of merges changed user-visible behavior: CLI flags, API shapes, default values, configuration keys, endpoints, environment variables, supported versions.
- A user-reported bug traced back to outdated documentation.
- A release is being cut and the docs need a pass against the merged commits.
- A new feature shipped but only the engineer's PR description describes how to use it.

## When not to use

- The change is internal-only (private helper rename, refactor) with no user-visible impact.
- You want to "improve the docs" without a behavior anchor. That is a separate scoped project, not maintenance — make a plan first.

## The pass

1. **Establish the baseline.** Get the commit range you are documenting against (since last release tag, since last merged-doc commit, or since a specific PR).
2. **Enumerate user-visible changes.** Read commits and PR descriptions. List, for each change, what a user can now do differently.
3. **Map changes to docs.** For each change, find every page that mentions the affected concept. Common targets: README, CLI reference, API reference, configuration reference, migration guide, FAQ, examples.
4. **Update precisely.** Edit only the lines that need to change. Do not rewrap paragraphs you did not modify — it pollutes the diff.
5. **Add new entries where needed.** New CLI flag → CLI reference entry. New env var → configuration reference entry. New endpoint → API reference entry. Don't only add it to the changelog.
6. **Update examples and snippets.** Code blocks in docs are wrong faster than prose. Re-run any example that touches new behavior.
7. **Write the release note.** One sentence per user-visible change. Group by Added / Changed / Fixed / Deprecated / Removed. Link to the relevant PRs and docs section.
8. **Cross-check.** Search the docs for the old behavior wording and remove or update stragglers.

## Style baseline

- Voice: second person ("you can pass `--json` to ..."). Avoid "we" except in narrative pages.
- Tense: present, not future. The behavior exists once shipped.
- Headings: imperative ("Configure the cache") or noun-phrase ("Cache configuration"), match the surrounding page.
- Code blocks: include the language tag so syntax highlighting works.
- Cross-links: link the first mention of a concept on each page; do not link every occurrence.
- Avoid promising future behavior. If something is unreleased, mark it `experimental` or omit it.

## Drift detection

A doc page is drifting if any of these are true:

- It documents a flag, key, or endpoint that no longer exists.
- An example does not run as written.
- A default value in the docs does not match the code.
- A supported-versions list excludes a version the project actually supports, or includes one it dropped.
- A "Coming soon" section references a feature that shipped or was cancelled.

When you find drift, fix it in the same pass and note it in the release note's `Fixed` group.

## Release-note rules

- One sentence per item. If two sentences are needed, the item is likely two items.
- User impact first, internal cause second. `Faster cold start (avoid full bundle download on first run)` beats `Refactor bootstrap loader`.
- Link the PR for engineering readers and the docs page for users.
- Mark breaking changes explicitly: `**Breaking:**` prefix. Include migration steps inline or via link.

## Anti-patterns

- Massive doc PRs that bundle stylistic rewrites with real updates. Reviewers cannot tell which lines reflect actual behavior changes.
- "Updated docs" commit messages with no detail. Make the commit say what changed and why.
- Adding to the changelog without updating the reference docs the changelog points to.
- Marking a feature as available before its code lands. Documentation must follow behavior, not promise it.


---
*Source: https://skills.yangsir.net/skill/gh-doc-maintenance*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-doc-maintenance/markdown*