chore: Add agent instructions for working with docs#561
Conversation
developerjamiu
left a comment
There was a problem hiding this comment.
This PR captures most of the rules perfectly.
Some rules we apply across reviews that aren't captured here:
- No em dashes (—): Hard to read aloud, almost always substitutable with a comma, parenthesis, or period. Splitting usually improves the prose.
- 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
dataPathsetting..." - Cross-doc link form: strip numeric folder prefixes: Use
../concepts/authentication/setupnot../06-concepts/11-authentication/01-setup. Numbered paths break the Docusaurus broken-link check on strict mode. - 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:robust→reliable;seamless→smooth; "enables you to X" → "lets you X" or "you can X". - 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:
2, 3 and 5:
|
|
|
||
| ### 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. |
There was a problem hiding this comment.
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.
| 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
left a comment
There was a problem hiding this comment.
Minor text change otherwise all looks good.
This PR introduces tooling to help maintainers, contributors, and LLM agents write and review documentation consistently.
The goal is to improve:
New file: docs.instructions.md
A code review instructions file (auto-applied to docs/, versioned_docs/, cloud_docs/**).
It defines:
Four page templates
Page skeletons for when creating new pages:
Test results
Tested using Cursor to review 7 files in the tree. Some screenshot from the review results: