Skip to content

chore: Add agent instructions for working with docs#561

Open
Swiftaxe wants to merge 3 commits into
mainfrom
docs/agent-skills
Open

chore: Add agent instructions for working with docs#561
Swiftaxe wants to merge 3 commits into
mainfrom
docs/agent-skills

Conversation

@Swiftaxe

@Swiftaxe Swiftaxe commented May 29, 2026

Copy link
Copy Markdown
Collaborator

This PR introduces tooling to help maintainers, contributors, and LLM agents write and review documentation consistently.

The goal is to improve:

  • Efficiency
  • Quality
  • Consistency

New file: docs.instructions.md

A code review instructions file (auto-applied to docs/, versioned_docs/, cloud_docs/**).

It defines:

  • 16 named noise patterns with bad/good examples drawn from real PR review comments
  • Core writing principles and guidelines
  • Review guidelines
  • Structure rules
  • Helpers for when creating new pages.

Four page templates

Page skeletons for when creating new pages:

  • Concept
  • Guide
  • Tutorial
  • Reference

Test results

Tested using Cursor to review 7 files in the tree. Some screenshot from the review results:

image image

@Swiftaxe Swiftaxe requested review from Zfinix and developerjamiu May 29, 2026 13:08
@Swiftaxe Swiftaxe changed the title chore: Add agent skills for working with docs chore: Add agent instructions for working with docs Jun 9, 2026
Comment thread .github/instructions/docs.instructions.md Outdated
Comment thread .github/instructions/docs.instructions.md Outdated

@developerjamiu developerjamiu left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This PR captures most of the rules perfectly.

Some rules we apply across reviews that aren't captured here:

  1. No em dashes (—): Hard to read aloud, almost always substitutable with a comma, parenthesis, or period. Splitting usually improves the prose.
  2. Don't start a sentence or paragraph with an inline code span: A backtick-wrapped identifier at the start reads as a symbol, not a sentence. Lead with a noun phrase: "The dataPath setting..."
  3. Cross-doc link form: strip numeric folder prefixes: Use ../concepts/authentication/setup not ../06-concepts/11-authentication/01-setup. Numbered paths break the Docusaurus broken-link check on strict mode.
  4. Avoid complex vocabulary that adds friction without adding meaning: Examples to avoid: robust, seamless, powerful, intuitive, leverage, facilitate, enables you to. Prefer the plain version: robustreliable; seamlesssmooth; "enables you to X" → "lets you X" or "you can X".
  5. Don't preview a linked page using terms the reader hasn't met: A Related entry that names .scloudignore only works if the page already explained it. Otherwise describe what the linked page is for using terms the reader knows.

Each of these has shown up in recent PR reviews.

@Swiftaxe

Swiftaxe commented Jun 9, 2026

Copy link
Copy Markdown
Collaborator Author

This PR captures most of the rules perfectly.

Some rules we apply across reviews that aren't captured here:

  1. No em dashes (—): Hard to read aloud, almost always substitutable with a comma, parenthesis, or period. Splitting usually improves the prose.
  2. Don't start a sentence or paragraph with an inline code span: A backtick-wrapped identifier at the start reads as a symbol, not a sentence. Lead with a noun phrase: "The dataPath setting..."
  3. Cross-doc link form: strip numeric folder prefixes: Use ../concepts/authentication/setup not ../06-concepts/11-authentication/01-setup. Numbered paths break the Docusaurus broken-link check on strict mode.
  4. Avoid complex vocabulary that adds friction without adding meaning: Examples to avoid: robust, seamless, powerful, intuitive, leverage, facilitate, enables you to. Prefer the plain version: robustreliable; seamlesssmooth; "enables you to X" → "lets you X" or "you can X".
  5. Don't preview a linked page using terms the reader hasn't met: A Related entry that names .scloudignore only works if the page already explained it. Otherwise describe what the linked page is for using terms the reader knows.

Each of these has shown up in recent PR reviews.

1 and 4 was added to the style guide instead:

  • New §1 "Words to avoid" subsection with a lookup table for friction vocabulary substitutions (robust → reliable, leverage → use, etc.)
  • New §8 Em dashes section with a before/after example

2, 3 and 5:

  • Three new docs-specific patterns added: sentence-starting code span (15), numbered link prefixes (16), opaque Related entry (17)

@Swiftaxe Swiftaxe requested a review from developerjamiu June 9, 2026 19:02

### 12. Version history noise

Describing old Serverpod behavior in a current task page. The reader is completing a task with the current version; what the framework used to do is irrelevant unless they are migrating.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Nit: pattern 12 body still says "task page". The address-review note mentioned the replacement to "guides and tutorials"; pattern 13 got the disambiguation via the "Applies to guides and tutorials" line, but this one was missed.

Suggested change
Describing old Serverpod behavior in a current task page. The reader is completing a task with the current version; what the framework used to do is irrelevant unless they are migrating.
Describing old Serverpod behavior in a current guide or tutorial. The reader is completing a task with the current version; what the framework used to do is irrelevant unless they are migrating.

@developerjamiu developerjamiu left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Minor text change otherwise all looks good.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants