skills docs.instructions.md

Preamble

The rules in this document apply to all "documentation-style" content. That can be markdown files (.md or .mdx), JSDoc or TSDoc docblocks (/** ... */), Rust DocComments /// ..., Python docstrings (""" ... """), or any other similar format.

They do not need to be applied to code or to comments that are not intended for end users (e.g., comments in source code meant for developers working on the codebase). Examples of this would be JavaScript inline comments (//), normal JavaScript block comments (/* ... */), Python comments (# ...), or Rust comments (// or /* ... */).

---

Primary Directive

Generate documentation content strictly adhering to the Apollo Voice and all rules in this guide.

---

Voice

The Apollo voice is:

• Approachable
• Positive
• Encouraging
• Helpful
• Opinionated/Authoritative

Opinionated voice prescribes a specific "happy path" to accomplish a goal.

Do this: "To achieve optimal performance, configure your server with X." Do this: "The recommended approach is to use Apollo Federation for scaling." Do this: "Always secure your GraphQL endpoint using authentication." Don't do this: "You can configure your server with X, Y, or Z." Reason: This is unopinionated and lays out options rather than prescribing a path. Don't do this: "There are several ways to scale, including Federation or stitching." Reason: This is unopinionated and presents multiple options without guiding the user. Don't do this: "Consider securing your GraphQL endpoint; options include authentication and authorization." Reason: This is unopinionated and doesn't prescribe a specific security measure.

The Apollo voice is not:

• Sarcastic
• Condescending
• Robotic
• Exaggerated
• Unopinionated

Guiding Principle: Communicate as if with a coworker you haven't met yet.

---

Language

• Spelling and Grammar: Use American English. Do this: "The request is canceled." Do this: "The client is customizing their schema." Do this: "The solution centralizes data management." Don't do this: "The request is cancelled." Reason: Uses British English spelling. Don't do this: "The client is customising their schema." Reason: Uses British English spelling. Don't do this: "The solution centralises data management." Reason: Uses British English spelling.
• Simplicity: Keep language simple and avoid idioms. Do this: "The client's query was very fast." Do this: "This feature makes development easier." Do this: "The system is now fully functional." Don't do this: "The client's query was lightning fast." Reason: Uses an idiom that may not be understood by non-native English speakers. Don't do this: "This feature is a piece of cake for developers." Reason: Uses an idiom. Don't do this: "The system is now firing on all cylinders." Reason: Uses an idiom.