Skip to content

docs: explain purpose of /edit-the-docs in CONTRIBUTING.md rather than the "Write the docs" checklist - #50313

Open
nrichers wants to merge 3 commits into
masterfrom
write-the-docs-checklist-updates
Open

docs: explain purpose of /edit-the-docs in CONTRIBUTING.md rather than the "Write the docs" checklist#50313
nrichers wants to merge 3 commits into
masterfrom
write-the-docs-checklist-updates

Conversation

@nrichers

@nrichers nrichers commented Sep 13, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

I have read the CONTRIBUTING.md file.

YES

What kind of change does this PR introduce?

Docs authoring guidance: keep /edit-the-docs out of the Write the docs checklist and document when to use what skill in CONTRIBUTING.md.

What is the current behavior?

The Write the docs checklist mentions /edit-the-docs mid-flow and lists it among checklist skills. That skill is a different workflow and audience, so it risks steering people off the six-stage process.

What is the new behavior?

  • Checklist lists only Write the docs skills; no /edit-the-docs mid-stage note.
  • CONTRIBUTING.md splits Write the docs skills from Edit existing pages.
  • Write the docs applies when product intent and code drive the change, including revising or restructuring existing pages. edit-the-docs is for style, structure, or brevity when the product story is unchanged.

Additional context

Also drops a redundant /test-the-docs note from "What good looks like" (Self-review still covers it).

@nrichers
nrichers requested a review from a team as a code owner September 13, 2026 19:16
@vercel

vercel Bot commented Sep 13, 2026 •
edited
Loading

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
docs Ready Ready Preview, v0 Sep 13, 2026 9:10pm UTC
7 Skipped Deployments
Project Deployment Actions Updated
studio Ignored Ignored Sep 13, 2026 9:10pm UTC
design-system Skipped Skipped Sep 13, 2026 9:10pm UTC
kb Skipped Skipped Sep 13, 2026 9:10pm UTC
studio-self-hosted Skipped Skipped Sep 13, 2026 9:10pm UTC
studio-staging Skipped Skipped Sep 13, 2026 9:10pm UTC
ui-library Skipped Skipped Sep 13, 2026 9:10pm UTC
zone-www-dot-com Skipped Skipped Sep 13, 2026 9:10pm UTC

Request Review

@supabase

supabase Bot commented Sep 13, 2026

Copy link
Copy Markdown

This pull request has been ignored for the connected project xguihxuzqibwxjnimxev because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Sep 13, 2026
nrichers
nrichers commented Sep 13, 2026
View reviewed changes
Comment thread .agents/skills/pm-the-docs/reference/write-the-docs-checklist.md
- The content **type is deliberate** and consistent within the page.
- **Audience and prerequisites** are stated up front.
- **Examples are runnable and have been tested** (commands, code, expected result) — verify with `/test-the-docs` against a Docker-isolated local stack, not production.
- **Examples are runnable and have been tested** (commands, code, expected result)

@nrichers nrichers Sep 13, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor unrelated clean-up.

@coderabbitai

coderabbitai Bot commented Sep 13, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Review Change StackReview Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 2adeaf28-2db5-4dc3-b9ef-78fe8eaf9e62

📥 Commits

Reviewing files that changed from the base of the PR and between fbd9dbb and 32e6167.

📒 Files selected for processing (1)
  • apps/docs/CONTRIBUTING.md
🚧 Files skipped from review as they are similar to previous changes (1)
  • apps/docs/CONTRIBUTING.md

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

📝 Walkthrough

Walkthrough

The documentation checklist removes /edit-the-docs references. The contributing guide updates slash-command instructions, revises writing-skill descriptions, and adds separate guidance for editing existing pages.

Changes

Documentation skill guidance

Layer / File(s) Summary
Checklist skill references
.agents/skills/pm-the-docs/reference/write-the-docs-checklist.md		 The checklist removes the Docker-isolated testing instruction and references to /edit-the-docs.
Contributor skill workflow
apps/docs/CONTRIBUTING.md		 The guide updates skill invocation and descriptions, separates writing guidance from editing guidance, and moves edit-the-docs into a dedicated subsection.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~8 minutes

Change: Other

Suggested reviewers: czenko, alaister

Merge Risk: ⚪ Minimal · up to 32e61

The documentation-only changes have no identified merge-blocking risk.

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Title check ✅ Passed The title clearly describes the main change: moving /edit-the-docs guidance from the Write the docs checklist to CONTRIBUTING.md.
Description check ✅ Passed The description includes all required sections. It confirms the contributor guide was read, identifies the change as documentation guidance, explains the current and new behavior, and provides additio…
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch write-the-docs-checklist-updates

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@vercel
vercel Bot temporarily deployed to Preview – kb September 13, 2026 21:06 Inactive
@nrichers
nrichers requested a review from czenko September 13, 2026 21:10
@nrichers nrichers changed the title docs: reference purpose of /edit-the-docs in CONTRIBUTING.md rather than the "Write the docs" checklist docs: explain purpose of /edit-the-docs in CONTRIBUTING.md rather than the "Write the docs" checklist Sep 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@czenko czenko Awaiting requested review from czenko

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

documentation Improvements or additions to documentation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@nrichers