igniter-js writing-style.instructions.md

✍️ Unified Documentation Style Guide (for LLMs & Authors)

This guide defines the writing standards for all Igniter.js content: documentation, blog posts, templates, and updates.

🎯 Core Style Principles (Applies to All Documentation)

1. Clarity Over Cleverness
   Use simple, direct language. Favor short words and short sentences. Avoid jargon unless it's essential—and if it is, define it once.

2. Speak Developer
   Write the way you'd speak to a smart, curious engineer sitting next to you. Friendly, confident, and precise.

3. Show, Don't Just Tell
   Use examples liberally. Explain ideas with real code, not abstract theory. Every key concept should be backed by a working snippet.

4. Write in Active Voice
   ✅ "Click the button to save your changes."
   ❌ "The button should be clicked in order for changes to be saved."

5. Present First, Explain Later
   Get the reader to success as quickly as possible. After they've seen something work, then explain how/why it works.

6. Be Honest and Human
   If something is tricky, say so. If you're recommending a workaround, explain why. Transparency builds trust.

7. Use consistent terminology
   Always refer to concepts, components, and APIs by the same name. Don't mix "endpoint" and "route" if they mean the same thing.

---

📘 Documentation (Docs): Writing Style

Tone: Clear, technical, and helpful
Voice: An expert engineer sharing knowledge directly

✅ Style Rules:

• Use second person ("you") to address developers directly
• Always include conversational introduction paragraphs at the start of major sections explaining what, why, and how
• Keep explanations focused and concise but provide enough context
• Start with working examples, then explain concepts
• Use <Callout> for important notes and warnings
• Include complete, runnable code examples
• Structure with <Steps> for sequential instructions (wrap in <Card> when representing complete guides)
• Use <Tabs> for package manager commands (with groupId="package-manager")
• Add <TypeTable> for API reference documentation
• Show file structures with <Files>, <Folder>, <File> components
• Convert lists to Accordions for "Best Practices", "Limitations", "Common Use Cases", and similar sections
• Never include "Next Steps" sections in documentation articles (only in blog posts/tutorials)
• Expand "Complete Example" sections with detailed introductory paragraphs explaining what the example demonstrates