Skip to content

Commit 52d345e

Browse files
github-actions[bot]Copilotdsyme
authored
Add Documentation Unbloat workflow (#169)
Add high-value workflow from Peli's Agent Factory to automatically simplify documentation by removing verbosity while maintaining clarity. This workflow achieved an 85% merge rate (88 merged out of 103 PRs) in the gh-aw repository, demonstrating strong practical value. Key features: - Removes duplicate content and excessive bullet points - Consolidates redundant examples and verbose descriptions - Preserves all essential information and technical accuracy - Works one file at a time for easy review - Tracks cleaned files in cache memory to avoid duplication - Supports slash command /unbloat in PR comments Source: https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/unbloat-docs.md Documented merge rate: 88/103 PRs merged (85%) Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Don Syme <dsyme@users.noreply.github.com>
1 parent 6c7124b commit 52d345e

3 files changed

Lines changed: 465 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@ You can use the "/plan" agent to turn the reports into actionable issues which c
5151
- [📖 Daily Documentation Updater](docs/daily-doc-updater.md) - Automatically update documentation based on recent code changes and merged PRs
5252
- [📖 Glossary Maintainer](docs/glossary-maintainer.md) - Automatically maintain project glossary based on codebase changes
5353
- [🔗 Link Checker](docs/link-checker.md) - Daily automated link checker that finds and fixes broken links in documentation
54+
- [🗜️ Documentation Unbloat](docs/unbloat-docs.md) - Automatically simplify documentation by reducing verbosity while maintaining clarity
5455
- [✨ Code Simplifier](docs/code-simplifier.md) - Automatically simplify recently modified code for improved clarity and maintainability
5556
- [🔍 Duplicate Code Detector](docs/duplicate-code-detector.md) - Identify duplicate code patterns and suggest refactoring opportunities
5657
- [⚡ Daily Progress](docs/daily-progress.md) - Automated daily feature development following a structured roadmap

‎docs/unbloat-docs.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# 🗜️ Documentation Unbloat
2+
3+
> For an overview of all available workflows, see the [main README](../README.md).
4+
5+
The [Documentation Unbloat workflow](../workflows/unbloat-docs.md?plain=1) automatically reviews and simplifies documentation by removing verbosity while maintaining clarity and completeness.
6+
7+
## Installation
8+
9+
````bash
10+
# Install the 'gh aw' extension
11+
gh extension install github/gh-aw
12+
13+
# Add the workflow to your repository
14+
gh aw add-wizard githubnext/agentics/unbloat-docs
15+
````
16+
17+
This walks you through adding the workflow to your repository.
18+
19+
You can start a run of this workflow immediately by running:
20+
21+
````bash
22+
gh aw run unbloat-docs
23+
````
24+
25+
Or trigger it in a pull request comment with:
26+
27+
````
28+
/unbloat
29+
````
30+
31+
## What It Does
32+
33+
The Documentation Unbloat workflow runs daily and can be triggered via `/unbloat` command in PR comments. It:
34+
35+
1. **Scans Documentation** - Reviews markdown files in the repository for bloat
36+
2. **Identifies Verbosity** - Finds duplicate content, excessive bullet points, redundant examples, and verbose descriptions
37+
3. **Removes Bloat** - Makes targeted edits to improve clarity and conciseness
38+
4. **Preserves Accuracy** - Maintains all essential information, links, and technical details
39+
5. **Creates Pull Requests** - Proposes documentation improvements one file at a time for easy review
40+
41+
## How It Works
42+
43+
### What Gets Removed
44+
45+
The workflow identifies and removes:
46+
47+
- **Duplicate content**: Same information repeated in different sections
48+
- **Excessive bullet points**: Long lists that could be condensed into prose or tables
49+
- **Redundant examples**: Multiple examples showing the same concept
50+
- **Verbose descriptions**: Overly wordy explanations
51+
- **Repetitive structure**: Overused "What it does" / "Why it's valuable" patterns
52+
53+
### What Gets Preserved
54+
55+
The workflow never removes:
56+
57+
- Technical accuracy or specific details
58+
- Links to external resources
59+
- Code examples (though duplicates may be consolidated)
60+
- Critical warnings or notes
61+
- Frontmatter metadata
62+
63+
### One File at a Time
64+
65+
The workflow improves exactly **one file per run** to keep changes small, focused, and easily reviewable. This incremental approach makes it easier to:
66+
67+
- Review and approve changes quickly
68+
- Understand what was modified
69+
- Revert changes if needed
70+
- Track improvements over time
71+
72+
### Protected Files
73+
74+
Files can be protected from automatic editing by adding `disable-agentic-editing: true` to their frontmatter. The workflow automatically skips:
75+
76+
- Auto-generated documentation
77+
- Changelog or release notes
78+
- License or legal files
79+
- Files marked with `disable-agentic-editing: true`
80+
81+
### Memory and Tracking
82+
83+
The workflow uses cache memory to track previously cleaned files, avoiding duplicate work and ensuring efficient coverage of documentation over time.
84+
85+
## Trigger Options
86+
87+
### Daily Schedule
88+
89+
Runs automatically once per day at a scattered execution time to continuously improve documentation.
90+
91+
### Slash Command
92+
93+
Trigger on-demand in pull request comments:
94+
95+
````
96+
/unbloat
97+
````
98+
99+
This analyzes documentation files modified in the PR and proposes improvements.
100+
101+
### Manual Trigger
102+
103+
Run manually via GitHub Actions UI or CLI:
104+
105+
````bash
106+
gh aw run unbloat-docs
107+
````
108+
109+
## Success Criteria
110+
111+
A successful run:
112+
113+
- ✅ Improves exactly **one** documentation file
114+
- ✅ Reduces bloat by at least 20% (lines, words, or bullet points)
115+
- ✅ Preserves all essential information
116+
- ✅ Creates a clear, reviewable pull request
117+
- ✅ Explains the improvements made
118+
119+
## Benefits
120+
121+
**Improved Readability**: Concise documentation is easier to scan and understand, helping users find information faster.
122+
123+
**Reduced Maintenance**: Shorter documentation is easier to keep up-to-date as the project evolves.
124+
125+
**Better User Experience**: Clear, focused content reduces cognitive load and improves comprehension.
126+
127+
**Continuous Improvement**: Daily runs ensure documentation stays lean as new content is added.
128+
129+
## Example Improvements
130+
131+
### Before (Bloated)
132+
133+
````markdown
134+
### Tool Name
135+
Description of the tool.
136+
137+
- **What it does**: This tool does X, Y, and Z
138+
- **Why it's valuable**: It's valuable because A, B, and C
139+
- **How to use**: You use it by doing steps 1, 2, 3, 4, 5
140+
- **When to use**: Use it when you need X
141+
- **Benefits**: Gets you benefit A, benefit B, benefit C
142+
- **Learn more**: [Link](url)
143+
````
144+
145+
### After (Concise)
146+
147+
````markdown
148+
### Tool Name
149+
Description of the tool that does X, Y, and Z to achieve A, B, and C.
150+
151+
Use it when you need X by following steps 1-5. [Learn more](url)
152+
````
153+
154+
## Customization
155+
156+
You can customize the workflow by editing the [`unbloat-docs.md`](../workflows/unbloat-docs.md) file:
157+
158+
- Adjust which directories or file patterns to scan
159+
- Modify the success criteria (e.g., minimum bloat reduction percentage)
160+
- Change the PR labeling and auto-merge behavior
161+
- Add project-specific exclusion patterns
162+
- Customize the tone or style guidance
163+
164+
After making changes, recompile the workflow:
165+
166+
````bash
167+
gh aw compile unbloat-docs
168+
````
169+
170+
## Complementary Workflows
171+
172+
This workflow pairs well with:
173+
174+
- [Daily Documentation Updater](daily-doc-updater.md) - Ensures accuracy and completeness
175+
- [Glossary Maintainer](glossary-maintainer.md) - Keeps terminology consistent
176+
- [Link Checker](link-checker.md) - Validates all documentation links
177+
178+
Together, these workflows maintain comprehensive, accurate, and readable documentation.

0 commit comments

Comments
 (0)