Writing style guide

This guide adapts the MDN writing style guide for this knowledge base. Goal: clear, concise, consistent—so readers can quickly tell whether a page has the answer they need.

General principles

Know your audience

• Decide who you’re writing for: beginner, intermediate, or personal review notes.
• Keep difficulty consistent within a domain; link to index pages for cross-domain context instead of piling unrelated background into one article.

The 3C’s

Criterion	Meaning
Clear	Short sentences, one idea each; define new terms; prefer active voice.
Concise	Only what the reader needs; details belong in child pages; index pages stay navigational.
Consistent	Same terms site-wide; heading levels and file naming follow Principles.

Intro paragraphs (important)

Before the first heading, use 1–3 paragraphs to state:

1. What the page covers and which problem it solves
2. What the reader can do or understand after reading
3. (Optional) Prerequisite articles

note

Too short: “This page introduces Swift concurrency.” — scope and payoff unclear.
Too long: dumping API details in the intro — move them into body sections.

Examples and code

• Pair each important concept with at least one runnable example or real scenario.
• Use fenced blocks with optional title for language/file; inline code with backticks.
• Put edge cases in their own short section, not buried in long paragraphs.

Inclusive language

Avoid master/slave, allow/deny list phrasing where simpler neutral terms work; use “the user”, “they”, or rephrase to avoid unnecessary gender.

SEO (optional)

• Include likely search terms naturally in the title and first paragraph—no keyword stuffing.
• Use descriptive link text; avoid “click here”.

Page structure (MDN-style)

Recommended order:

1. Lead (paragraphs before the first ##)
2. ## sections — main chapters
3. ### subsections — details
4. References / further reading — external links and related on-site pages

Admonitions

Docusaurus admonitions work like MDN notes and warnings:

:::note
Supplementary context that doesn’t interrupt the main flow.
:::

:::tip
A easier approach or practical shortcut.
:::

:::warning
Cautions for investing, health, legal, or similar topics.
:::

:::info
Background or “read more” pointers.
:::

tip

Use admonitions sparingly—2–4 per page is usually enough.

Related guides on this site

Doc	Purpose
Principles	Structure, naming, collaboration
Outline	File tree and sidebar
Monetization	AdSense configuration

References

• MDN writing style guide
• MDN how to write documentation