Writing Content

Great documentation doesn’t happen by accident. Follow these guidelines to create content that helps users succeed — and keeps them coming back.

Structure your pages

Every documentation page should follow a consistent pattern:

1. Clear title — what the reader will learn
2. Brief introduction — why this matters (2–3 sentences)
3. Step-by-step content — scannable sections with headings
4. Next steps — link to related pages

Use MDX components

Scholar ships with reusable components you can import in MDX files:

import Callout from '../../components/ui/Callout.astro';

<Callout type="tip" title="Pro tip">
  Use callouts to highlight important information.
</Callout>

Writing style

• Use second person (“you”) to speak directly to the reader
• Keep sentences short and paragraphs focused
• Include code examples for every concept you explain
• Mark placeholder content clearly as example copy

SEO considerations

Each page’s frontmatter description field becomes the meta description. Write unique, descriptive summaries for every page.