1# Command Documentation Patterns
2 
3Strategies for creating self-documenting, maintainable commands with excellent user experience.
4 
5## Overview
6 
7Well-documented commands are easier to use, maintain, and distribute. Documentation should be embedded in the command itself, making it immediately accessible to users and maintainers.
8 
9## Self-Documenting Command Structure
10 
11### Complete Command Template
12 
13```markdown
14---
15description: Clear, actionable description under 60 chars
16argument-hint: [arg1] [arg2] [optional-arg]
17allowed-tools: Read, Bash(git:*)
18model: sonnet
19---
20 
21<!--
22COMMAND: command-name
23VERSION: 1.0.0
24AUTHOR: Team Name
25LAST UPDATED: 2025-01-15
26 
27PURPOSE:
28Detailed explanation of what this command does and why it exists.
29 
30USAGE:
31  /command-name arg1 arg2
32 
33ARGUMENTS:
34  arg1: Description of first argument (required)
35  arg2: Description of second argument (optional, defaults to X)
36 
37EXAMPLES:
38  /command-name feature-branch main
39    → Compares feature-branch with main
40 
41  /command-name my-branch
42    → Compares my-branch with current branch
43 
44REQUIREMENTS:
45  - Git repository
46  - Branch must exist
47  - Permissions to read repository
48 
49RELATED COMMANDS:
50  /other-command - Related functionality
51  /another-command - Alternative approach
52 
53TROUBLESHOOTING:
54  - If branch not found: Check branch name spelling
55  - If permission denied: Check repository access
56 
57CHANGELOG:
58  v1.0.0 (2025-01-15): Initial release
59  v0.9.0 (2025-01-10): Beta version
60-->
61 
62# Command Implementation
63 
64[Command prompt content here...]
65 
66[Explain what will happen...]
67 
68[Guide user through steps...]
69 
70[Provide clear output...]
71```
72 
73### Documentation Comment Sections
74 
75**PURPOSE**: Why the command exists
76- Problem it solves
77- Use cases
78- When to use vs when not to use
79 
80**USAGE**: Basic syntax
81- Command invocation pattern
82- Required vs optional arguments
83- Default values
84 
85**ARGUMENTS**: Detailed argument documentation
86- Each argument described
87- Type information
88- Valid values/ranges
89- Defaults
90 
91**EXAMPLES**: Concrete usage examples
92- Common use cases
93- Edge cases
94- Expected outputs
95 
96**REQUIREMENTS**: Prerequisites
97- Dependencies
98- Permissions
99- Environmental setup
100 
101**RELATED COMMANDS**: Connections
102- Similar commands
103- Complementary commands
104- Alternative approaches
105 
106**TROUBLESHOOTING**: Common issues
107- Known problems
108- Solutions
109- Workarounds
110 
111**CHANGELOG**: Version history
112- What changed when
113- Breaking changes highlighted
114- Migration guidance
115 
116## In-Line Documentation Patterns
117 
118### Commented Sections
119 
120```markdown
121---
122description: Complex multi-step command
123---
124 
125<!-- SECTION 1: VALIDATION -->
126<!-- This section checks prerequisites before proceeding -->
127 
128Checking prerequisites...
129- Git repository: !`git rev-parse --git-dir 2>/dev/null`
130- Branch exists: [validation logic]
131 
132<!-- SECTION 2: ANALYSIS -->
133<!-- Analyzes the differences between branches -->
134 
135Analyzing differences between $1 and $2...
136[Analysis logic...]
137 
138<!-- SECTION 3: RECOMMENDATIONS -->
139<!-- Provides actionable recommendations -->
140 
141Based on analysis, recommend:
142[Recommendations...]
143 
144<!-- END: Next steps for user -->
145```
146 
147### Inline Explanations
148 
149```markdown
150---
151description: Deployment command with inline docs
152---
153 
154# Deploy to $1
155 
156## Pre-flight Checks
157 
158<!-- We check branch status to prevent deploying from wrong branch -->
159Current branch: !`git branch --show-current`
160 
161<!-- Production deploys must come from main/master -->
162if [ "$1" = "production" ] && [ "$(git branch --show-current)" != "main" ]; then
163  ⚠️  WARNING: Not on main branch for production deploy
164  This is unusual. Confirm this is intentional.
165fi
166 
167<!-- Test status ensures we don't deploy broken code -->
168Running tests: !`npm test`
169 
170✓ All checks passed
171 
172## Deployment
173 
174<!-- Actual deployment happens here -->
175<!-- Uses blue-green strategy for zero-downtime -->
176Deploying to $1 environment...
177[Deployment steps...]
178 
179<!-- Post-deployment verification -->
180Verifying deployment health...
181[Health checks...]
182 
183Deployment complete!
184 
185## Next Steps
186 
187<!-- Guide user on what to do after deployment -->
1881. Monitor logs: /logs $1
1892. Run smoke tests: /smoke-test $1
1903. Notify team: /notify-deployment $1
191```
192 
193### Decision Point Documentation
194 
195```markdown
196---
197description: Interactive deployment command
198---
199 
200# Interactive Deployment
201 
202## Configuration Review
203 
204Target: $1
205Current version: !`cat version.txt`
206New version: $2
207 
208<!-- DECISION POINT: User confirms configuration -->
209<!-- This pause allows user to verify everything is correct -->
210<!-- We can't automatically proceed because deployment is risky -->
211 
212Review the above configuration.
213 
214**Continue with deployment?**
215- Reply "yes" to proceed
216- Reply "no" to cancel
217- Reply "edit" to modify configuration
218 
219[Await user input before continuing...]
220 
221<!-- After user confirms, we proceed with deployment -->
222<!-- All subsequent steps are automated -->
223 
224Proceeding with deployment...
225```
226 
227## Help Text Patterns
228 
229### Built-in Help Command
230 
231Create a help subcommand for complex commands:
232 
233```markdown
234---
235description: Main command with help
236argument-hint: [subcommand] [args]
237---
238 
239# Command Processor
240 
241if [ "$1" = "help" ] || [ "$1" = "--help" ] || [ "$1" = "-h" ]; then
242  **Command Help**
243 
244  USAGE:
245    /command [subcommand] [args]
246 
247  SUBCOMMANDS:
248    init [name]       Initialize new configuration
249    deploy [env]      Deploy to environment
250    status            Show current status
251    rollback          Rollback last deployment
252    help              Show this help
253 
254  EXAMPLES:
255    /command init my-project
256    /command deploy staging
257    /command status
258    /command rollback
259 
260  For detailed help on a subcommand:
261    /command [subcommand] --help
262 
263  Exit.
264fi
265 
266[Regular command processing...]
267```
268 
269### Contextual Help
270 
271Provide help based on context:
272 
273```markdown
274---
275description: Context-aware command
276argument-hint: [operation] [target]
277---
278 
279# Context-Aware Operation
280 
281if [ -z "$1" ]; then
282  **No operation specified**
283 
284  Available operations:
285  - analyze: Analyze target for issues
286  - fix: Apply automatic fixes
287  - report: Generate detailed report
288 
289  Usage: /command [operation] [target]
290 
291  Examples:
292    /command analyze src/
293    /command fix src/app.js
294    /command report
295 
296  Run /command help for more details.
297 
298  Exit.
299fi
300 
301[Command continues if operation provided...]
302```
303 
304## Error Message Documentation
305 
306### Helpful Error Messages
307 
308```markdown
309---
310description: Command with good error messages
311---
312 
313# Validation Command
314 
315if [ -z "$1" ]; then
316  ❌ ERROR: Missing required argument
317 
318  The 'file-path' argument is required.
319 
320  USAGE:
321    /validate [file-path]
322 
323  EXAMPLE:
324    /validate src/app.js
325 
326  Try again with a file path.
327 
328  Exit.
329fi
330 
331if [ ! -f "$1" ]; then
332  ❌ ERROR: File not found: $1
333 
334  The specified file does not exist or is not accessible.
335 
336  COMMON CAUSES:
337  1. Typo in file path
338  2. File was deleted or moved
339  3. Insufficient permissions
340 
341  SUGGESTIONS:
342  - Check spelling: $1
343  - Verify file exists: ls -la $(dirname "$1")
344  - Check permissions: ls -l "$1"
345 
346  Exit.
347fi
348 
349[Command continues if validation passes...]
350```
351 
352### Error Recovery Guidance
353 
354```markdown
355---
356description: Command with recovery guidance
357---
358 
359# Operation Command
360 
361Running operation...
362 
363!`risky-operation.sh`
364 
365if [ $? -ne 0 ]; then
366  ❌ OPERATION FAILED
367 
368  The operation encountered an error and could not complete.
369 
370  WHAT HAPPENED:
371  The risky-operation.sh script returned a non-zero exit code.
372 
373  WHAT THIS MEANS:
374  - Changes may be partially applied
375  - System may be in inconsistent state
376  - Manual intervention may be needed
377 
378  RECOVERY STEPS:
379  1. Check operation logs: cat /tmp/operation.log
380  2. Verify system state: /check-state
381  3. If needed, rollback: /rollback-operation
382  4. Fix underlying issue
383  5. Retry operation: /retry-operation
384 
385  NEED HELP?
386  - Check troubleshooting guide: /help troubleshooting
387  - Contact support with error code: ERR_OP_FAILED_001
388 
389  Exit.
390fi
391```
392 
393## Usage Example Documentation
394 
395### Embedded Examples
396 
397```markdown
398---
399description: Command with embedded examples
400---
401 
402# Feature Command
403 
404This command performs feature analysis with multiple options.
405 
406## Basic Usage
407 
408\`\`\`
409/feature analyze src/
410\`\`\`
411 
412Analyzes all files in src/ directory for feature usage.
413 
414## Advanced Usage
415 
416\`\`\`
417/feature analyze src/ --detailed
418\`\`\`
419 
420Provides detailed analysis including:
421- Feature breakdown by file
422- Usage patterns
423- Optimization suggestions
424 
425## Use Cases
426 
427**Use Case 1: Quick overview**
428\`\`\`
429/feature analyze .
430\`\`\`
431Get high-level feature summary of entire project.
432 
433**Use Case 2: Specific directory**
434\`\`\`
435/feature analyze src/components
436\`\`\`
437Focus analysis on components directory only.
438 
439**Use Case 3: Comparison**
440\`\`\`
441/feature analyze src/ --compare baseline.json
442\`\`\`
443Compare current features against baseline.
444 
445---
446 
447Now processing your request...
448 
449[Command implementation...]
450```
451 
452### Example-Driven Documentation
453 
454```markdown
455---
456description: Example-heavy command
457---
458 
459# Transformation Command
460 
461## What This Does
462 
463Transforms data from one format to another.
464 
465## Examples First
466 
467### Example 1: JSON to YAML
468**Input:** `data.json`
469\`\`\`json
470{"name": "test", "value": 42}
471\`\`\`
472 
473**Command:** `/transform data.json yaml`
474 
475**Output:** `data.yaml`
476\`\`\`yaml
477name: test
478value: 42
479\`\`\`
480 
481### Example 2: CSV to JSON
482**Input:** `data.csv`
483\`\`\`csv
484name,value
485test,42
486\`\`\`
487 
488**Command:** `/transform data.csv json`
489 
490**Output:** `data.json`
491\`\`\`json
492[{"name": "test", "value": "42"}]
493\`\`\`
494 
495### Example 3: With Options
496**Command:** `/transform data.json yaml --pretty --sort-keys`
497 
498**Result:** Formatted YAML with sorted keys
499 
500---
501 
502## Your Transformation
503 
504File: $1
505Format: $2
506 
507[Perform transformation...]
508```
509 
510## Maintenance Documentation
511 
512### Version and Changelog
513 
514```markdown
515<!--
516VERSION: 2.1.0
517LAST UPDATED: 2025-01-15
518AUTHOR: DevOps Team
519 
520CHANGELOG:
521  v2.1.0 (2025-01-15):
522    - Added support for YAML configuration
523    - Improved error messages
524    - Fixed bug with special characters in arguments
525 
526  v2.0.0 (2025-01-01):
527    - BREAKING: Changed argument order
528    - BREAKING: Removed deprecated --old-flag
529    - Added new validation checks
530    - Migration guide: /migration-v2
531 
532  v1.5.0 (2024-12-15):
533    - Added --verbose flag
534    - Improved performance by 50%
535 
536  v1.0.0 (2024-12-01):
537    - Initial stable release
538 
539MIGRATION NOTES:
540  From v1.x to v2.0:
541    Old: /command arg1 arg2 --old-flag
542    New: /command arg2 arg1
543 
544  The --old-flag is removed. Use --new-flag instead.
545 
546DEPRECATION WARNINGS:
547  - The --legacy-mode flag is deprecated as of v2.1.0
548  - Will be removed in v3.0.0 (estimated 2025-06-01)
549  - Use --modern-mode instead
550 
551KNOWN ISSUES:
552  - #123: Slow performance with large files (workaround: use --stream flag)
553  - #456: Special characters in Windows (fix planned for v2.2.0)
554-->
555```
556 
557### Maintenance Notes
558 
559```markdown
560<!--
561MAINTENANCE NOTES:
562 
563CODE STRUCTURE:
564  - Lines 1-50: Argument parsing and validation
565  - Lines 51-100: Main processing logic
566  - Lines 101-150: Output formatting
567  - Lines 151-200: Error handling
568 
569DEPENDENCIES:
570  - Requires git 2.x or later
571  - Uses jq for JSON processing
572  - Needs bash 4.0+ for associative arrays
573 
574PERFORMANCE:
575  - Fast path for small inputs (< 1MB)
576  - Streams large files to avoid memory issues
577  - Caches results in /tmp for 1 hour
578 
579SECURITY CONSIDERATIONS:
580  - Validates all inputs to prevent injection
581  - Uses allowed-tools to limit Bash access
582  - No credentials in command file
583 
584TESTING:
585  - Unit tests: tests/command-test.sh
586  - Integration tests: tests/integration/
587  - Manual test checklist: tests/manual-checklist.md
588 
589FUTURE IMPROVEMENTS:
590  - TODO: Add support for TOML format
591  - TODO: Implement parallel processing
592  - TODO: Add progress bar for large files
593 
594RELATED FILES:
595  - lib/parser.sh: Shared parsing logic
596  - lib/formatter.sh: Output formatting
597  - config/defaults.yml: Default configuration
598-->
599```
600 
601## README Documentation
602 
603Commands should have companion README files:
604 
605```markdown
606# Command Name
607 
608Brief description of what the command does.
609 
610## Installation
611 
612This command is part of the [plugin-name] plugin.
613 
614Install with:
615\`\`\`
616/plugin install plugin-name
617\`\`\`
618 
619## Usage
620 
621Basic usage:
622\`\`\`
623/command-name [arg1] [arg2]
624\`\`\`
625 
626## Arguments
627 
628- `arg1`: Description (required)
629- `arg2`: Description (optional, defaults to X)
630 
631## Examples
632 
633### Example 1: Basic Usage
634\`\`\`
635/command-name value1 value2
636\`\`\`
637 
638Description of what happens.
639 
640### Example 2: Advanced Usage
641\`\`\`
642/command-name value1 --option
643\`\`\`
644 
645Description of advanced feature.
646 
647## Configuration
648 
649Optional configuration file: `.claude/command-name.local.md`
650 
651\`\`\`markdown
652---
653default_arg: value
654enable_feature: true
655---
656\`\`\`
657 
658## Requirements
659 
660- Git 2.x or later
661- jq (for JSON processing)
662- Node.js 14+ (optional, for advanced features)
663 
664## Troubleshooting
665 
666### Issue: Command not found
667 
668**Solution:** Ensure plugin is installed and enabled.
669 
670### Issue: Permission denied
671 
672**Solution:** Check file permissions and allowed-tools setting.
673 
674## Contributing
675 
676Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
677 
678## License
679 
680MIT License - See [LICENSE](LICENSE).
681 
682## Support
683 
684- Issues: https://github.com/user/plugin/issues
685- Docs: https://docs.example.com
686- Email: [email protected]
687```
688 
689## Best Practices
690 
691### Documentation Principles
692 
6931. **Write for your future self**: Assume you'll forget details
6942. **Examples before explanations**: Show, then tell
6953. **Progressive disclosure**: Basic info first, details available
6964. **Keep it current**: Update docs when code changes
6975. **Test your docs**: Verify examples actually work
698 
699### Documentation Locations
700 
7011. **In command file**: Core usage, examples, inline explanations
7022. **README**: Installation, configuration, troubleshooting
7033. **Separate docs**: Detailed guides, tutorials, API reference
7044. **Comments**: Implementation details for maintainers
705 
706### Documentation Style
707 
7081. **Clear and concise**: No unnecessary words
7092. **Active voice**: "Run the command" not "The command can be run"
7103. **Consistent terminology**: Use same terms throughout
7114. **Formatted well**: Use headings, lists, code blocks
7125. **Accessible**: Assume reader is beginner
713 
714### Documentation Maintenance
715 
7161. **Version everything**: Track what changed when
7172. **Deprecate gracefully**: Warn before removing features
7183. **Migration guides**: Help users upgrade
7194. **Archive old docs**: Keep old versions accessible
7205. **Review regularly**: Ensure docs match reality
721 
722## Documentation Checklist
723 
724Before releasing a command:
725 
726- [ ] Description in frontmatter is clear
727- [ ] argument-hint documents all arguments
728- [ ] Usage examples in comments
729- [ ] Common use cases shown
730- [ ] Error messages are helpful
731- [ ] Requirements documented
732- [ ] Related commands listed
733- [ ] Changelog maintained
734- [ ] Version number updated
735- [ ] README created/updated
736- [ ] Examples actually work
737- [ ] Troubleshooting section complete
738 
739With good documentation, commands become self-service, reducing support burden and improving user experience.
740