Style Guide

This style guide outlines the writing principles for Agpedia.

General principles

• Audience: Agpedia is written for a general audience. While we rely on diverse sources (academic, primary, etc.), we maintain our own accessible tone and do not necessarily adopt the style of our sources.
• Tone: We generally write in an encyclopedic style, grounding claims with citations. Analysis and value judgments should be clearly distinguished and placed in dedicated sections.
• Formatting:
  • Bold is used sparingly. In the lead section, bold the article title on its first occurrence, and also bold significant alternative names by which the subject is also known (e.g., "Mumbai, also known as Bombay..."). Do not bold the title again elsewhere in the article. Outside the lead, bold may be used in lists or tables to highlight key terms, but avoid over-bolding.
  • Italics may be used for emphasis and are generally used for titles of works (e.g., books, movies).
• Structure: Tables are encouraged to help readers navigate complex information.
• Perspective: While Agpedia is guided by its values, avoid being self-referential. For example, describe the impact on human agency directly ("this policy has effectively limited access to health insurance") rather than explaining why we are noting it.

Technical level and accessibility

Write for a reader who is intelligent and broadly educated, but has no prior knowledge of the topic. The goal is not to simplify — it is to be clear. Technical depth and accessibility are not opposites: a well-written technical article is both precise and followable.

• Define terms on first use. Do not assume familiarity with jargon or field-specific vocabulary. Gloss a technical term the first time it appears, even if it seems obvious in context. If the term has its own article, link it; otherwise define it inline.
• Lead with the general, then the specific. The lead section should be comprehensible without domain knowledge. Technical depth belongs in body sections, where a reader who wants more can follow.
• Prefer plain words when precision is not lost. When a simpler word is equally precise, choose it ("use" over "utilize", "shows" over "demonstrates"). Do not simplify when it changes or weakens the meaning.
• Avoid nominalization where possible. Prefer "the system failed" over "failure of the system occurred." Dense noun chains obscure meaning without adding precision.
• Use examples and analogies freely. A concrete example or analogy makes a concept genuinely accessible without sacrificing accuracy. This is not dumbing down — it is good expository writing.

Names across languages

Article prose is written in the language of that article's version. Non-English names (relative to the article's language) appear in parentheses after the name used in the prose on first use, not woven into the running text.

• Format for native names. Label each name with its language before the term: French: Genève, German: Genf. Italicise text where the script supports it; do not italicise non-Latin scripts (Arabic, Chinese, Cyrillic, etc.) since the script distinction is visually sufficient. For non-Latin scripts, include a romanisation: (Arabic: عمّان, ʿAmmān).
• Multiple official languages. Where a subject has names in several official languages — for example, Swiss place names in German, French, Italian, and Romansh — list all relevant names in the same parenthetical, separated by semicolons: (German: Genf; French: Genève; Italian: Ginevra; Romansh: Genevra). These names should be bolded in the lead per the bolding rule, since they are significant alternative names by which the subject is known.
• Article title and slug. Use the name most commonly associated with the subject in the article's language. If no established form exists in that language, use the name from the language most closely associated with the subject (e.g. for a French village with no established name in the article language, use the French name). Document the choice in the lead parenthetical so it is transparent to readers.
• Subsequent mentions. After the first-use parenthetical, use whichever name flows naturally in prose — typically the article-language name or the slug name. Do not repeat the parenthetical.
• When to include native names. Not every article needs them. Include native-language names for place names, institutions, and proper nouns tied to a specific language community, or where the original-language form is commonly referenced in sources. Omit them when they add no useful information.

Headings

• H1 is reserved for the page title and is never used within article body content. Sections use H2; subsections use H3 and beyond.
• Page titles use AP Style title case: capitalize the first and last words, all "major" words (nouns, verbs, adjectives, adverbs), and prepositions of four or more letters; lowercase articles (a, an, the), coordinating conjunctions (and, but, or, nor, for, so, yet), and prepositions of three or fewer letters unless they open the title.
• Section headings (H2 and below) use sentence case — capitalize only the first word and proper nouns (e.g., "History of the labour movement", not "History of the Labour Movement").

Lead section

• Every article should begin with a lead section — body text that appears before the first H2 heading. The lead requires no heading of its own.
• The lead should be one to four paragraphs long and function as a self-contained overview of the article. A reader who reads only the lead should come away with an accurate summary of the topic.
• The first sentence should define or identify the subject concisely. For biographical articles, it should state the person's full name, birth and death dates (where known), nationality, and primary claim to notability. For concepts, it should provide a plain-language definition.
• Emphasis in the lead should reflect the relative importance of each point — do not bury the most significant information.

Dates

• Write dates in the format January 1, 2020 — month name in full, followed by the day and four-digit year. Do not use ISO format (2020-01-01) or day-first format (1 January 2020) in article prose.

Links

Links connect articles and help readers navigate to related topics. Use them to aid understanding, not to decorate prose.

The primary test

For every term, ask: would a general reader — someone intelligent but unfamiliar with this subject — benefit from following this link? If yes, link it. If the term is so universally understood that no reader would need more context (e.g., "the internet", "a photograph"), skip it.

When in doubt, link. An unneeded link costs the reader a glance; a missing link on a term they don't know costs them comprehension.

What to always link on first occurrence

The following categories of terms almost always warrant a link, because readers unfamiliar with the topic will benefit from them:

• Named concepts, theories, and fields — e.g., reinforcement learning, causal decision theory, utilitarianism, FIDO2
• Named people — anyone who is not a universally known historical figure (e.g., link Toby Ord but not Abraham Lincoln)
• Named organizations and institutions — e.g., GiveWell, Mozilla Foundation, OWASP
• Named protocols, standards, and specifications — e.g., ActivityPub, WebAuthn, JSON-RPC
• Named laws and regulations — e.g., the BOTS Act, the Affordable Care Act
• Technical terms introduced in the article — any term that requires definition or prior knowledge to understand

The lead section deserves particular attention: it is the part of an article most readers will actually read, and every technical or specialized term introduced there should be linked.

Restraint rules

• Link on first occurrence only. Do not repeat a link for subsequent mentions of the same term in the same article.
• Internal links only. Do not include "See also" or "External links" sections. External links belong in citations, not in prose.
• Link whether or not the article exists. Links to pages that do not yet exist are encouraged — they signal gaps and invite future contributions.
• Do not link common words or universally known concepts. Terms like "government", "university", or "photograph" do not need links.
• Links belong in the flow of prose. Do not collect links at the end of sections or force them into lists purely for navigation.

Slugs

• Slugs are always lowercase; spaces are replaced with hyphens (e.g., barack-obama, not Barack_Obama).
• Article slugs live in the root namespace — e.g., /barack-obama. There is no /wiki/ or similar prefix.
• Pages that are not articles use a /meta/ prefix — e.g., /meta/style.
• Some prefixes are reserved by the software and must not be used for content pages. Notably, /tool/ is reserved for special software pages.

Words to watch

Avoid the following language patterns, which weaken verifiability or mislead readers:

• Puffery and promotional language: Words like leading, world-class, innovative, cutting-edge, or renowned assert significance without evidence. Replace with specific, sourced claims.
• Weasel words: Vague attributions like "some say," "many believe," "it has been suggested," or "critics argue" without identifying who actually makes the claim. Attribute opinions to named sources.
• Unsourced superlatives: Claims that something is "the first," "the largest," "the most important," etc., require a citation.
• Editorializing: Avoid inserting value judgments into factual prose without explicit labeling. If a value judgment is warranted, place it in a dedicated Analysis section and attribute it clearly per the Citation Standards.
• Vague intensifiers: Words like significant, important, notable, or key should be used only when backed by sourced evidence of significance, not as decoration.