Back to Details

docs-update

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation Update Workflow

文档更新工作流

Streamline documentation updates when code changes are made. This skill helps identify what documentation needs updating and guides you through the process.
代码变更后简化文档更新流程。本技能可帮助识别需要更新的文档内容，并引导你完成更新过程。

When to Use

使用场景

Use this skill after:
  • Adding new TUI keybindings
  • Adding new CLI commands or flags
  • Adding new config options
  • Changing default behavior
  • Adding new features or integrations
  • Modifying user-facing functionality
在以下场景后使用本技能：
  • 添加新的TUI快捷键
  • 添加新的CLI命令或参数
  • 添加新的配置选项
  • 修改默认行为
  • 添加新功能或集成
  • 调整面向用户的功能

Workflow

工作流

Step 1: Identify Changes

步骤1：识别变更内容

Analyze recent commits or current changes to identify documentation-impacting changes:
bash
undefined
分析最近的提交或当前变更，找出会影响文档的修改：
bash
undefined

Check uncommitted changes

查看未提交的变更

git diff
git diff

Check recent commits

查看最近的提交

git log -5 --oneline git show <commit-sha>
git log -5 --oneline git show <commit-sha>

Check specific files

查看特定文件的变更

git diff HEAD~1 internal/tui/model.go

**Look for:**
- New keybindings in TUI code
- New commands in CLI code
- New config fields
- Changed default values
- New features or integrations
git diff HEAD~1 internal/tui/model.go

**重点关注：**
- TUI代码中的新快捷键
- CLI代码中的新命令
- 新的配置字段
- 修改后的默认值
- 新功能或集成

Step 2: Find Relevant Documentation

步骤2：查找相关文档

Documentation files to check:
FileUpdate When
README.md
Keybindings, features, config options, CLI commands
docs/recipes/*.md
Integration-specific changes
CLI help textNew commands, flags, or changed behavior
Search commands:
bash
undefined
需要检查的文档文件：
文件更新时机
README.md
快捷键、功能、配置选项、CLI命令变更时
docs/recipes/*.md
集成相关的变更时
CLI帮助文本添加新命令、参数或修改行为时
搜索命令：
bash
undefined

Find documentation files

查找文档文件

find . -name ".md" -not -path "./agent-deck/" | head -20
find . -name ".md" -not -path "./agent-deck/" | head -20

Search for specific content

搜索特定内容

grep -r "keybindings" README.md docs/ grep -r "Default keybindings" README.md
undefined
grep -r "keybindings" README.md docs/ grep -r "Default keybindings" README.md
undefined

Step 3: Update Documentation

步骤3：更新文档

README.md Sections to Update

README.md需更新的章节

Default Keybindings (around line 311):
markdown
**Default keybindings:**

- `:` - Open command palette (when user commands configured)
- `v` - Toggle preview sidebar (shows tmux pane output)
- `r` - Recycle session
- `d` - Delete session
...
TUI Features (around line 303):
markdown
**Features:**

- Tree view of sessions grouped by repository
- Real-time terminal status monitoring (with tmux integration)
- Preview sidebar showing live tmux pane output (`v` to toggle)
...
Configuration Options (around line 238): Add new config fields to the table with type, default, and description.
CLI Reference (starting line 288): Add new commands or flags with descriptions and examples.
默认快捷键（约第311行）：
markdown
**Default keybindings:**

- `:` - Open command palette (when user commands configured)
- `v` - Toggle preview sidebar (shows tmux pane output)
- `r` - Recycle session
- `d` - Delete session
...
TUI功能（约第303行）：
markdown
**Features:**

- Tree view of sessions grouped by repository
- Real-time terminal status monitoring (with tmux integration)
- Preview sidebar showing live tmux pane output (`v` to toggle)
...
配置选项（约第238行）： 在表格中添加新的配置字段，包含类型、默认值和描述。
CLI参考（从第288行开始）： 添加新命令或参数，包含描述和示例。

Recipe Updates

使用指南更新

Update 
docs/recipes/tmux-integration.md
when:
  • Adding tmux-specific keybindings
  • Changing tmux integration behavior
  • Adding new status indicators
当出现以下情况时更新
docs/recipes/tmux-integration.md
：
  • 添加tmux专属快捷键
  • 修改tmux集成行为
  • 添加新的状态指示器

Step 4: Verify Updates

步骤4：验证更新

Check that documentation is accurate and complete:
bash
undefined
检查文档的准确性和完整性：
bash
undefined

Search for old keybinding references

搜索旧快捷键的引用

grep -r "old-key" README.md docs/
grep -r "old-key" README.md docs/

Verify all new features are documented

验证所有新功能都已记录

grep -r "new-feature" README.md
grep -r "new-feature" README.md

Check for consistency

检查一致性

grep -rn "keybindings" README.md
undefined
grep -rn "keybindings" README.md
undefined

Step 5: Commit

步骤5：提交变更

Commit documentation changes separately from code changes:
bash
git add README.md docs/
git commit -m "docs: describe what was updated

Detailed description of changes."
将文档变更与代码变更分开提交：
bash
git add README.md docs/
git commit -m "docs: describe what was updated

Detailed description of changes."

Examples

示例

Example 1: New TUI Keybinding

示例1：新增TUI快捷键

Change: Added 
v
key to toggle preview sidebar
Documentation Updates:
  1. README.md line ~315: Add 
    v
    key to keybindings list
  2. README.md line ~305: Add preview feature to features list
  3. Verify no other mentions of keybindings need updating
Commit:
bash
git add README.md
git commit -m "docs: add preview sidebar to TUI features and keybindings

Document the new 'v' key for toggling the tmux pane preview sidebar
in the default keybindings list and TUI features section."
变更内容： 添加
v
键用于切换预览侧边栏
文档更新：
  1. README.md约第315行：在快捷键列表中添加
    v
    键
  2. README.md约第305行：在功能列表中添加预览功能
  3. 确认没有其他提及快捷键的地方需要更新
提交命令：
bash
git add README.md
git commit -m "docs: add preview sidebar to TUI features and keybindings

Document the new 'v' key for toggling the tmux pane preview sidebar
in the default keybindings list and TUI features section."

Example 2: New Config Option

示例2：新增配置选项

Change: Added 
tui.preview_enabled
config option
Documentation Updates:
  1. README.md Configuration Options table: Add new row with type, default, description
  2. README.md Config example: Add to YAML example if commonly used
  3. Check if any recipes should mention it
变更内容： 添加
tui.preview_enabled
配置选项
文档更新：
  1. README.md配置选项表格：添加新行，包含类型、默认值和描述
  2. README.md配置示例：如果是常用配置，添加到YAML示例中
  3. 检查是否有使用指南需要提及该选项

Example 3: New CLI Command

示例3：新增CLI命令

Change: Added 
hive preview
command
Documentation Updates:
  1. README.md CLI Reference: Add new section with command description
  2. Add flag table if command has flags
  3. Add usage examples
  4. Update command list in Quick Start if relevant
变更内容： 添加
hive preview
命令
文档更新：
  1. README.md CLI参考：添加新章节，包含命令描述
  2. 如果命令有参数，添加参数表格
  3. 添加使用示例
  4. 如果相关，更新快速入门中的命令列表

Checklist

检查清单

Use this checklist for every documentation update:
  • Identified all code changes that impact users
  • Found all relevant documentation files
  • Updated README.md keybindings (if applicable)
  • Updated README.md features list (if applicable)
  • Updated README.md config options (if applicable)
  • Updated README.md CLI reference (if applicable)
  • Updated recipes (if applicable)
  • Searched for old references to changed behavior
  • Verified accuracy of all updates
  • Committed with clear message
每次更新文档时使用以下检查清单：
  • 已识别所有影响用户的代码变更
  • 已找到所有相关文档文件
  • 已更新README.md中的快捷键（如适用）
  • 已更新README.md中的功能列表（如适用）
  • 已更新README.md中的配置选项（如适用）
  • 已更新README.md中的CLI参考（如适用）
  • 已更新使用指南（如适用）
  • 已搜索并清理旧行为的引用
  • 已验证所有更新的准确性
  • 已使用清晰的提交信息提交

Tips

小贴士

Be Proactive:
  • Update docs in the same PR as code changes when possible
  • Review documentation as part of code review
Be Thorough:
  • Search for all mentions of changed behavior
  • Update examples to match new behavior
  • Check both inline docs and separate files
Be Clear:
  • Use consistent terminology
  • Provide examples for complex features
  • Document the "why" not just the "what"
Keep Organized:
  • Separate doc commits from code commits when updating after the fact
  • Use descriptive commit messages
  • Link docs commits to related code commits
主动更新：
  • 尽可能在同一个PR中同时更新代码和文档
  • 将文档审查作为代码审查的一部分
全面细致：
  • 搜索所有提及变更行为的地方
  • 更新示例以匹配新行为
  • 同时检查内联文档和独立文件
清晰易懂：
  • 使用一致的术语
  • 为复杂功能提供示例
  • 不仅记录“是什么”，还要记录“为什么”
保持条理：
  • 事后更新时，将文档提交与代码提交分开
  • 使用描述性的提交信息
  • 将文档提交与相关代码提交关联