Copy Style Guide

Text, Tone, and Grammar

General Do's and Don'ts


  • Run all final drafts through Grammarly.

  • Use short, concise sentences. People have little time to browse.

  • Use basic language. Remove unnecessary words.

  • Assume users are unfamiliar with the system. Link to basic terms when necessary.

  • Use pluralized, gender-neutral pronouns. Use “they/their” instead of “he/she/his/hers.” (e.g., “When they…” or “If users choose to X, then their…”)

  • Remain open and objective.

  • Provide examples when possible. Do not complicate them with complex numbers.

  • Explain with math when needed; otherwise, keep it simple.

  • Do not spell out "percent.” Use the symbol (e.g., "15%" instead of "15 percent").

  • Use double quotes " " for phrases, quotes, etc., not ' '.


  • Exclamation points.

  • Second person language in tutorials or FAQs.

    (i.e., "You then..." or "Now you should...")

  • Em or en dashes .

  • References to Purple Paper names (flip, flap, flop, etc.) in the documentation.

  • Footnotes.

  • Curly quotes . Use the plaintext version: ".

  • Escaping parentheses, \(SOMETHING\). Use normal parentheses, (SOMETHING).

  • Ampersands & in titles and headers



  • Anything that has a definition provided by MakerDAO. The capitalization is an indicator to the world that it's a special term.

  • Names and other proper nouns

  • Cities, Countries, Nationalities, and Languages

  • In titles, the first word, all nouns, all verbs, all adjectives, and all proper nouns. That means you should lowercase articles(a, an, the) conjunctions(and, but, etc.), and prepositions(on, it, before, etc.).


  • Spell out numbers below 10 (e.g., one, two, three...).

  • Use numerals for numbers above 10, except when starting a sentence.

  • Use figures with million, billion, and trillion in all except casual uses.

    (e.g., "I'd like to make a billion dollars." vs. "The nation has 1 million citizens.")


  • Dollars: Use lowercase except when writing "US Dollar.”:

    • Use figures and the \"$" sign in all except casual references or amounts without a figure. (e.g., "The book cost $4." vs. "Please give me a dollar.")

    • For amounts less than $1 million: $4, $25, $500, $1,000, $650,000.

    • For amounts over $1 million, use the word, not numerals. (e.g., "He is worth $4 million" instead of "He is worth $4,000,000.")

  • Apply the same rules to other foreign currencies.


  • When making acronyms plural, simply add an "s" (e.g., "SCDs").


  • Do not use apostrophes to indicate decades (e.g., "the 1990s" instead of "1990’s").

Naming Conventions and Proper Nouns


  • If directly referring to the creation, destruction, or manipulation of the token (particularly as it relates to tooling), use the capitalized TLA version: DAI.

    In the same manner, refer to exchange pairs: DAI/ETH.

  • If referencing it as a currency, in an instructional or conversational setting, or as a conceptual product of the foundation or its systems, use: Dai.


:exclamation: Save yourself some trouble. Use VSCode and install the Prettier extension. It auto-corrects 90% of your markdown mistakes.


  • Consider using Visual Studio Code and install:

    • Markdown Preview Enhanced, Markdown Linter, Code Spell Checker, Prettier, GitLens

  • Include line breaks above and below headings.

  • Do not make multiple top-level headings. Only use # once per document.

  • Do not use the same heading twice. It breaks auto-generated navigation.

  • Do not leave trailing spaces.

  • Ensure there is a single hard return at the end of the file.

  • Ensure the file is updated for every document that should show up in GitBook.


When bulleted and numbered lists contain complete sentences, capitalize the first word, and follow each with a period. If list items are phrases, no capitalization or punctuation is required. Also:

  • Use parallel construction for each item in a list.

  • Start with the same part of speech for each item (in this example, a verb).

  • Use the same verb tense for each item.

  • Use the same voice for each item.

  • Use the same sentence type (statement, question, exclamation) for each item.

  • Alphabetize all lists of names unless there is a clear priority at work.

  • Use dashes rather than asterisks for unordered lists (i.e. - not *).

  • Do not use ordered (numbered) lists unless order matters.

  • Ordered list items should use the #1 repeated:

    1. Item 1
    1. Item 2
    1. Item 3
    1. Item 3a
    1. Item 3b

File Names

  • Filenames contain information specific to the contents of the file. Context is provided from the directory or through the presentation layer:, not

  • Filenames are to be lowercase and words separated with -.



  • Ensure repositories are up to date.

  • Commit early and commit often. Submit changes before large merges.

  • Discuss efforts in #community-development.

  • Ask for feedback before starting long projects.

  • Make descriptive commit messages:

    • Incorrect: "Fixed something"

    • Correct: "Fixed spelling mistakes in"


  • Use descriptive hyperlinks. Avoid generic terms:

  • When creating links for parallel translated documents, ensure relative links are updated to reflect the correct heading:

    en: faqs/
    es: faqs/es/é-son-las-posiciones-de-deuda-colateralizadascdp
    ko: faqs/ko/부채-담보부-포지션collateralized-debt-positions-cdp이란-무엇인가요

FAQ Style Guide

  • Always use relative links.

  • Look for terms to add to the Glossary.

  • Important numbers should be bold: "A CDP exists with 1000 DAI Stability Debt."

  • List items that include definitions should look like this:

    • Team: Core team and advisors are critical to MakerDAO's success.

    • Community: Sentiment analysis is invaluable.

  • Wrap formulas in inline code blocks.

  • The first example defines the terms:

    (((Total Stability Debt in DAI * (1 + Current Governance Fee in decimal format)) ^ (Age of Stability Debt in days/365)) * Total Stability Debt in DAI ) = Total Governance Debt owed in DAI

  • The second example contains the numbers and the result:

    (1000 * (1 + 0.005) ^ (30÷365)) * 1000 = 0.410018954 DAI

  • Wrap examples, tips, tricks, and notes in code fencing when formatting needs to be preserved or color-coding is useful.

    Note: Liquidation is bad. Don't be liquidated.


    use a quote

Complex Topics

  • Include parameters for reference:

    CDP Settings


    MKR Price via Oracle Feed


    ETH Price via Oracle Feed


  • Provide a user story or an easy-to-follow example.

  • Add example formulas for advanced topics and/or if they further discussion.

Sample Values

  • Use the same values for system Globals and Risk Parameters in all examples. This lowers the cognitive load required to parse numbers.

  • These are the default values. Copy and paste from below:

    CDP Settings


    MKR Price via Oracle Feed


    Total Stability Debt in DAI


    Age of Stability Debt in days


    Governance Fee


    Liquidation Penalty


    Spread (Bust/Boom)


    Stability Fee


    Target Rate