docs: add comprehensive documentation guidelines for worker skill bundles#137
Conversation
…dles This commit introduces a new file, DOCUMENTATION_GUIDELINES.md, which outlines the structure and requirements for authoring worker skill bundles. It details the necessary folder layout, YAML frontmatter specifications, and the required sections for each function's documentation. The guidelines aim to ensure consistency and clarity across all worker documentation, facilitating easier navigation and understanding for users.
📝 WalkthroughWalkthroughThis PR adds ChangesSkill Bundle Documentation Guidelines
Possibly related PRs
Poem
🎯 3 (Moderate) | ⏱️ ~20 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
skill-check — worker0 verified, 25 skipped (no docs/).
Three for three. Nicely done. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@DOCUMENTATION_GUIDELINES.md`:
- Line 274: The phrase "rendered markdown document" in
DOCUMENTATION_GUIDELINES.md should use the proper noun capitalization; update
the text so "rendered markdown document" becomes "rendered Markdown document"
(i.e., replace the lowercase "markdown" with "Markdown" wherever that exact
phrase appears).
- Around line 312-314: The document has a contradictory rule about where
optional sections go: the single-function variant says optional sections slot
between `# Outputs` and `# Worked example`, but the multi-function text (lines
describing "Any applicable optional sections...") claims they go after `# Worked
example` and that this is "same as the single-function variant"; fix by making
the multi-function description consistent with the single-function ordering—edit
the sentence that begins "Any applicable optional sections..." so it states that
optional sections appear between `# Outputs` and `# Worked example` (before `#
Worked example` and before `# Related`), or if the intent was to differ, remove
"same as the single-function variant" and add a short justification for the
differing placement; update the wording accordingly wherever the phrase appears
to eliminate the contradiction.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: f834091a-b1e7-4fb5-b6f3-57712f6675fe
📒 Files selected for processing (1)
DOCUMENTATION_GUIDELINES.md
|
|
||
| ### `# Rendering rules` | ||
|
|
||
| **Required** when the function returns a rendered markdown document (a |
There was a problem hiding this comment.
Capitalize "Markdown" as a proper noun.
"Markdown" is the proper name of the formatting language, so it should be capitalized.
Proposed fix
-**Required** when the function returns a rendered markdown document (a
+**Required** when the function returns a rendered Markdown document (a📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| **Required** when the function returns a rendered markdown document (a | |
| **Required** when the function returns a rendered Markdown document (a |
🧰 Tools
🪛 LanguageTool
[uncategorized] ~274-~274: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ...** when the function returns a rendered markdown document (a body field whose contents...
(MARKDOWN_NNP)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@DOCUMENTATION_GUIDELINES.md` at line 274, The phrase "rendered markdown
document" in DOCUMENTATION_GUIDELINES.md should use the proper noun
capitalization; update the text so "rendered markdown document" becomes
"rendered Markdown document" (i.e., replace the lowercase "markdown" with
"Markdown" wherever that exact phrase appears).
| - Any applicable optional sections (`# Side effects`, `# Caching`, | ||
| `# Rendering rules`) come after `# Worked example` and before | ||
| `# Related`, same as the single-function variant. |
There was a problem hiding this comment.
Critical inconsistency: Optional section placement contradicts single-function variant.
Lines 312-314 state that optional sections come "after # Worked example and before # Related" and claim this is "same as the single-function variant." However, lines 131-132 explicitly state that optional sections "slot in between # Outputs and # Worked example" for single-function how-tos.
This creates contradictory ordering:
- Single-function: Outputs → [Optional sections] → Worked example → Related
- Multi-function: Worked example → [Optional sections] → Related
Either the placement differs between variants (in which case line 314's "same as" claim is incorrect), or one of the placements is wrong.
Proposed fix
If optional sections should appear in the same relative position in both variants, update lines 312-314:
-- Any applicable optional sections (`# Side effects`, `# Caching`,
- `# Rendering rules`) come after `# Worked example` and before
- `# Related`, same as the single-function variant.
+- Any applicable optional sections (`# Side effects`, `# Caching`,
+ `# Rendering rules`) come after the per-function `## Outputs` blocks
+ and before `# Worked example`, same as the single-function variant.Alternatively, if the placement intentionally differs, remove the "same as" claim and document why:
-- Any applicable optional sections (`# Side effects`, `# Caching`,
- `# Rendering rules`) come after `# Worked example` and before
- `# Related`, same as the single-function variant.
+- Any applicable optional sections (`# Side effects`, `# Caching`,
+ `# Rendering rules`) come after `# Worked example` and before
+ `# Related`. (Note: This differs from single-function how-tos where
+ optional sections precede `# Worked example`.)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - Any applicable optional sections (`# Side effects`, `# Caching`, | |
| `# Rendering rules`) come after `# Worked example` and before | |
| `# Related`, same as the single-function variant. | |
| - Any applicable optional sections (`# Side effects`, `# Caching`, | |
| `# Rendering rules`) come after the per-function `## Outputs` blocks | |
| and before `# Worked example`, same as the single-function variant. |
| - Any applicable optional sections (`# Side effects`, `# Caching`, | |
| `# Rendering rules`) come after `# Worked example` and before | |
| `# Related`, same as the single-function variant. | |
| - Any applicable optional sections (`# Side effects`, `# Caching`, | |
| `# Rendering rules`) come after `# Worked example` and before | |
| `# Related`. (Note: This differs from single-function how-tos where | |
| optional sections precede `# Worked example`.) |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@DOCUMENTATION_GUIDELINES.md` around lines 312 - 314, The document has a
contradictory rule about where optional sections go: the single-function variant
says optional sections slot between `# Outputs` and `# Worked example`, but the
multi-function text (lines describing "Any applicable optional sections...")
claims they go after `# Worked example` and that this is "same as the
single-function variant"; fix by making the multi-function description
consistent with the single-function ordering—edit the sentence that begins "Any
applicable optional sections..." so it states that optional sections appear
between `# Outputs` and `# Worked example` (before `# Worked example` and before
`# Related`), or if the intent was to differ, remove "same as the
single-function variant" and add a short justification for the differing
placement; update the wording accordingly wherever the phrase appears to
eliminate the contradiction.
1 participant
This commit introduces a new file, DOCUMENTATION_GUIDELINES.md, which outlines the structure and requirements for authoring worker skill bundles. It details the necessary folder layout, YAML frontmatter specifications, and the required sections for each function's documentation. The guidelines aim to ensure consistency and clarity across all worker documentation, facilitating easier navigation and understanding for users.
Summary by CodeRabbit