| name | adonisjs-docs-writer |
| description | AdonisJS documentation writing style guide. Use when creating, editing, or reviewing AdonisJS documentation, tutorials, guides, or API references. Provides priority-ranked patterns for document structure, code examples, tone, warnings, and explanatory writing. Includes an interview workflow for gathering requirements when creating new documentation from scratch. |
AdonisJS Documentation Writer
Write clear, actionable AdonisJS documentation following priority-ranked patterns.
Core Workflow
- New docs: Use the interview process in references/interview-process.md
- Writing/editing: Follow critical rules below, consult references/full-guidelines.md for details
Critical Rules (Non-Negotiable)
Document Structure
Feature summary before overview: After the title, list what the guide covers as bullet points. Then write the Overview section explaining concepts.
# Exception Handling
This guide covers exception handling in AdonisJS. You will learn how to:
- Use the global exception handler
- Customize error handling for specific types
- Report errors to logging services
## Overview
Exception handling provides a centralized system for managing errors...
Start major topics with Overview: Provide context and purpose before technical details.
Code Examples
No sandwich pattern: Never explain code both before AND after. Choose one:
- Preferred: Explanation before code, with inline comments for details
- Alternative: Only inline comments within code
<!-- CORRECT: Explanation before + inline comments -->
Named middleware receive options. This middleware checks roles and terminates early if unauthorized.
```ts title="app/middleware/authorize_middleware.ts"
export default class AuthorizeMiddleware {
async handle(ctx: HttpContext, next: NextFn, options: AuthOptions) {
const user = auth.getUserOrFail()
// Check if user has required role
if (user.role !== options.role) {
return response.unauthorized()
}
await next()
}
}
Let's build a middleware that checks roles.
if (user.role !== options.role) { return response.unauthorized() }
This code checks whether the user's role matches the required role.
**Complete, runnable examples**: Include all imports and realistic usage. Never use pseudo-code.
**File paths on every code block**: Use `title="path/to/file.ts"` format.
**Highlight changes**: Use `// [!code ++]` for additions, `// [!code --]` for removals.
### Warnings and Errors
**Always include solutions**: Never show a problem without a fix.
```markdown
:::warning
In order for HMR to work, you must lazy-load controllers. Static imports won't reflect changes until restart.
```ts
// Wrong - static import
import PostsController from '#controllers/posts_controller'
// Correct - lazy load
import { controllers } from '#generated/controllers'
router.get('/posts', [controllers.Posts, 'index'])
:::
### Tone and Explanation
**Explain "why" not just "what"**: Every feature needs purpose and rationale.
**Natural prose flow**: Never use labeled sections like "What it does:", "Where it lives:". Write flowing sentences.
**Confident language**: Use "will", "must", "should". Avoid hedging with "might", "possibly".
**Direct address**: Use "you" and "your" to speak to the reader.
**No em dashes**: Use periods, commas, and parentheses instead.
### Formatting
**Inline code for technical terms**: Always use backticks for code, filenames, commands.
**Tables for comparisons only**: Use options component for parameters/properties, not tables.
**Complexity labels**: Mark sections as Basic, Intermediate, or Advanced when spanning skill levels.
## Quick Reference: When to Use What
| Element | Use For |
|---------|---------|
| `:::warning` | Critical issues that cause problems |
| `:::tip` | Common gotchas, best practices |
| `:::note` | General context |
| `::::options` | Parameters, config, properties |
| Tables | Feature comparisons only |
| `// [!code ++]` | Code additions |
| `// [!code --]` | Code removals |
## Detailed Guidelines
For comprehensive rules with examples, see [references/full-guidelines.md](references/full-guidelines.md).
For the interview process when creating new documentation, see [references/interview-process.md](references/interview-process.md).
