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…”)
Use oxford commas.
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 ' '.
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.
“. Use the plaintext version:
\(SOMETHING\). Use normal parentheses,
& 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.
See a list of these terms in the Glossary of Terms
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(
but, etc.), and prepositions(
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").
If directly referring to the creation, destruction, or manipulation of the token (particularly as it relates to tooling), use the capitalized TLA version:
In the same manner, refer to exchange pairs:
If referencing it as a currency, in an instructional or conversational setting, or as a conceptual product of the foundation or its systems, use:
: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,
Code Spell Checker,
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 SUMMARY.md 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.
Do not use ordered (numbered) lists unless order matters.
Ordered list items should use the #1 repeated:
1. Item 11. Item 21. Item 31. Item 3a1. Item 3b
Filenames contain information specific to the contents of the file. Context is provided from the directory or through the presentation layer:
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 filename.md"
When creating links for parallel translated documents, ensure relative links are updated to reflect the correct heading:
en: faqs/cdp.md#what-are-collateralized-debt-positionses: faqs/es/cdp.md#qué-son-las-posiciones-de-deuda-colateralizadascdpko: faqs/ko/cdp.md#부채-담보부-포지션collateralized-debt-positions-cdp이란-무엇인가요
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
Include parameters for reference:
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.
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:
MKR Price via Oracle Feed
Total Stability Debt in DAI
Age of Stability Debt in days