writing-styles

✍️ 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.

8. Verify Before Documenting
   NEVER assume API behavior. Always check the actual implementation in packages/ before writing code examples or documentation. Read source code, interfaces, and type definitions to ensure accuracy.

---

📘 Documentation (Docs): Writing Style

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

✅ Style Rules:

• Verify Implementation: Always check packages/ source code before documenting APIs
• Use second person ("you") to address developers directly
• Keep explanations focused and concise
• Start with working examples, then explain concepts
• Use <Callout> for important notes and warnings
• Include complete, runnable code examples that match actual APIs
• Structure with <Steps> for sequential instructions
• Use <Tabs> for package manager commands (with groupId="package-manager")
• Add <TypeTable> for API reference documentation
• Show file structures with <Files>, <Folder>, <File> components
• Never assume: If unsure about an API, search and read the implementation