Writing standards

This guide describes the style, formatting, and content standards for all MEGADOC documentation. Follow these rules to ensure clarity, consistency, and a great user experience.

---

Content standards

• Use active voice: "Deploy the application"
• Be specific: "Click the blue Deploy button"
• Include context: Explain why, not just how
• Add examples: Show real commands/code
• Use headings: Structure content logically
• Include visuals: Screenshots, diagrams

Avoid

• Passive voice: "The application should be deployed"
• Vague instructions: "Configure the settings"
• No context: Steps without explanation
• Missing examples: Abstract descriptions only
• Wall of text: No structure or breaks
• Text-only: No visual aids

---

Formatting guidelines

Headers and structure:

# Page Title (H1 - One per page)

## Main Sections (H2)

### Subsections (H3)

#### Details (H4 - Use sparingly)

Emphasis and highlighting:

**Bold text** for important terms
_Italic text_ for emphasis
`Code snippets` for commands/code

> Blockquotes for important notes

Lists and organization:

1. Numbered lists for sequential steps

- Bullet lists for related items

Links:

✅ Markdown links (preferred):
[Getting Started](getting-started/)
[External Site](https://example.com)

✅ HTML links (when styling needed):
<a href="onboarding/" class="nav-link">Onboarding</a>

❌ Never use .md extension in HTML href:
<a href="onboarding/">Onboarding</a>

Key link rules:

• Internal links: Use relative paths with trailing slash
• External links: Use complete absolute URLs
• HTML <a href> tags: MUST use trailing slash (no .md)
• Markdown [text](path) links: Trailing slash preferred
• Always use descriptive link text (avoid "click here")

---

Style guidelines

• Conversational but professional tone
• Direct and actionable instructions
• Encouraging and supportive
• Technically accurate and verified
• US English spelling
• Oxford comma usage
• Sentence case headers
• Consistent terminology (see glossary)

---

Required frontmatter

Every Markdown file under docs/ MUST include the following YAML frontmatter fields. Pages missing required fields fail make validate-frontmatter and the PR pipeline.

---
title: Page title
description: One-line description for SEO and previews
owner: team-name
lifecycle_status: active # or: draft, deprecated
last_reviewed: YYYY-MM-DD
tags:
  - relevant-tag
doc_type: how-to # or: reference, tutorial, explanation, adr, runbook, troubleshooting
---

Field rules:

• last_reviewed must be ISO YYYY-MM-DD.
• doc_type must be one of: how-to, reference, tutorial, explanation, adr, runbook, troubleshooting.
• tags must be a YAML list (flow [a, b] or block - a form).
• Pick a doc_type that matches the Diataxis intent of the page. Don't label a learning-oriented landing page as reference or vice versa.

Related references

• Style guide — repo-wide voice, terminology, and formatting conventions.
• Document templates — start new pages from the matching Diataxis template (how-to-template, concept-template, etc.).
• Advanced markdown — admonitions, grid cards, Mermaid, and other advanced patterns.