From e44e6dd9fe3b40a24539b21e161f85415e900d9e Mon Sep 17 00:00:00 2001 From: wbnns Date: Wed, 31 Jul 2024 01:31:38 +0000 Subject: [PATCH 1/3] feat(guides): Add Editorial Style Guide for Base --- README.md | 7 +- guide/guide.pdf => guides/brand-guide.pdf | Bin guides/editorial-style-guide.md | 189 ++++++++++++++++++++++ 3 files changed, 193 insertions(+), 3 deletions(-) rename guide/guide.pdf => guides/brand-guide.pdf (100%) create mode 100644 guides/editorial-style-guide.md diff --git a/README.md b/README.md index 6c98a5a..aee234e 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ # Base brand-kit -This repo contains a guide, fonts and logos for the Base brand. +This repo contains a [brand guide](guides/brand-guide.pdf) with fonts and logos as well as an [editorial style guide](guides/editorial-style-guide.md) for the Base. Base is a secure, low-cost, developer-friendly Ethereum L2 built to bring the next billion users onchain. It's built on Optimism’s open-source [OP Stack](https://stack.optimism.io/). @@ -26,9 +26,10 @@ Base is a secure, low-cost, developer-friendly Ethereum L2 built to bring the ne [![GitHub pull requests by-label](https://img.shields.io/github/issues-pr-raw/base-org/brand-kit)](https://github.com/base-org/brand-kit/pulls) [![GitHub Issues](https://img.shields.io/github/issues-raw/base-org/brand-kit.svg)](https://github.com/base-org/brand-kit/issues) -### Guide +### Guides -Please see [this PDF](guide/guide.pdf) overview. +- [Brand Guide](guides/brand-guide.pdf) +- [Editorial Style Guide](guides/editorial-style-guide.md) ### Fonts diff --git a/guide/guide.pdf b/guides/brand-guide.pdf similarity index 100% rename from guide/guide.pdf rename to guides/brand-guide.pdf diff --git a/guides/editorial-style-guide.md b/guides/editorial-style-guide.md new file mode 100644 index 0000000..ff3f83d --- /dev/null +++ b/guides/editorial-style-guide.md @@ -0,0 +1,189 @@ +# Base Editorial Style Guide + +This is the Base Editorial Style Guide, which exists to: + +- Ensure a baseline level of quality and consistency across all media types + +- Keep all contributors on the same page about editorial standards + +- Align all communications from Base tonally + +## About Base + +Base is an Ethereum Layer 2 (L2) network offering a secure, low-cost, developer-friendly way for anyone, anywhere, to build onchain. + +## Critical Style Conventions + +- Write ‘Base’, not BASE, Base Chain, or Base Network + +- Use the word ‘onchain’ instead of ‘web3’ or ‘crypto’ + +- Use technical terms sparingly, and when you do, work to explain them in full + +- When referring to price, use ETH and not USD + +## Writing Guidelines + +**Emphasize Base's vision** + +Base has a grand vision to bring a billion people onchain, and a more compact vision to build a global onchain economy that increases innovation, creativity, and freedom. Highlight how Base aims to make this decentralized future more accessible for everyone, everywhere. + +**Highlight progress and what’s next** + +When discussing Base's ongoing developments, celebrate recent milestones and accomplishments. Outline the key priorities and initiatives planned for the current or upcoming period, grounding them in Base's overarching vision and mission. Invite collaboration from the community, fostering an environment where external perspectives can contribute ideas and feedback. + +**Focus on concrete examples over abstract concepts** + +Avoid excessive abstract language about "web3" or technical language around “blockchains,” etc. Ground writing in concrete examples of what Base enables: Affordable transactions, seamless user onboarding, simple developer tooling, etc. + +**Use clear examples to illustrate concepts** + +While some technical depth is unavoidable, aim to make abstract web3 concepts accessible through clear examples and analogies. Compare new paradigms to familiar ones to build understanding. Use specifics and walk through sample user flows to demonstrate core value propositions. + +**Whenever possible, celebrate builders** + +Base exists to empower those building a decentralized future, and building can be defined with a wide net: Creators, artists, developers, writers, etc. Frequently highlight and celebrate the projects, people, and communities utilizing Base. + +**Be a bridge** + +Don't assume reader familiarity with crypto concepts. Use analogies and examples to make clear connections between the tools and platforms people know and the future Base is building + +## Tone and Voice + +”Although tone and voice are often used together, they are not at all the same thing. Voice is the overall **personality** of your brand and can be described in adjectives like helpful, witty, or friendly. \[…] your brand’s voice will not change. However, tone, or tone of voice, is the attitude of your writing for a particular content piece.” - Shelby Crawford + +**Voice** + +- Progressive and future-thinking + +- Conversational and human + +- Direct (e.g., using "offers" over "that aims to offer") + +- Optimistic but realistic (not overly idealistic) + +- Appreciative (not prideful) + +- Witty + +- Championing of builders + +- Relatable (using cultural references familiar to the audience) + +**Tone** + +- Brief and punchy, with clarity and impact + +- Avoids of overly technical jargon or corporate talk + +- Acknowledges challenges directly but remains solutions-oriented + +- Not too casual, but still conversational + +- Provides unique, thought-provoking insights + +- Engages in trending topics wisely (and rarely) + +- Offers compelling reasons to return through memorable and engaging content + +- Minimal use of emojis (one at most) + +Here’s an example of writing that feels appropriate in both tone and voice: + +“Base is bringing a billion people onchain. To bring the world onchain, we need to create a new internet that supports a global economy. We’re making this vision a reality through a million builders actively working to create what they love. Join us and let’s build the future together.” + +**More on tone and voice** + +- [Tone in Writing: A Simple Guide](https://jerryjenkins.com/tone-in-writing/) - ”**…voice is _what_ you say, and tone is _how_ you say it.**” + +- [A Word About Style, Voice, and Tone](https://www.umgc.edu/current-students/learning-resources/writing-center/online-guide-to-writing/tutorial/chapter3/ch3-21.html) - “When you hear an author talking inside your head, “voice” is what that author sounds like. \[…] You can develop your own voice in your writing by paying special attention to rhythm, diction, and punctuation.” + +- [Point of View](https://www.merriam-webster.com/words-at-play/point-of-view-first-second-third-person-difference) - First, second, or third person? Omniscient, limited, or objective? Check for consistency. + +## Clarity, Concision, and Flow + +“The goal is to make your paper as simple and clear, as immediately intelligible to the reader as possible. This doesn’t mean that you should ignore subtle and sophisticated complexities in your theory – but the challenge is to **state those complexities simply and clearly**. Avoid making your subject seem more complex than necessary (for example, if something “creates habits”, it’s probably neither necessary nor helpful to say that it “exhibits a habit-formation process”).” \~ [R. Wicks](https://www.academia.edu/75129398/Stylebook_Tips_on_Organization_Writing_and_Formatting) + +- **Tips for Improving Clarity** + + - [Sentence Clarity](https://owl.purdue.edu/owl/general_writing/mechanics/sentence_clarity.html) - Strategies for improving sentence clarity include using transitional words, properly placing subordinate clauses, and choosing action verbs over ‘be’ verbs (e.g. _is_, _are_). + + - [Plain Style](https://owl.purdue.edu/owl/general_writing/writing_style/plain_style%20.html) - Because we specialize in reducing complex topics into concise summaries that are digestible to the average user, Base encourages contributors to write in plain style. For example: opt for simple words like _use_ rather than _utilize_. + + - **Passive and Active Voice** - Base prefers active voice. Sometimes [passive voice can be rhetorically effective](https://owl.purdue.edu/owl/general_writing/academic_writing/active_and_passive_voice/choosing_passive_voice.html), but in most cases contributors should [change passive to active voice](https://owl.purdue.edu/owl/general_writing/academic_writing/active_and_passive_voice/changing_passive_to_active_voice.html). For example: + + - **Original:** “Experiences that are sticky, that make it easy for anyone to get started, and that offer a seamless user experience that abstracts onchain complexity as much as possible are what we’re looking for.” (passive) + + - **Edited:** “We’re looking for experiences that make it easy for anyone to get started and offer a seamless user experience that abstracts complexity as much as possible.” (active) + +- **Tips for Improving Concision** + + - Avoid redundancies. When in doubt, opt for two shorter sentences over one longer one. The [Hemingway App](https://hemingwayapp.com/) can point out areas for improvement. + + - Consult the Purdue OWL page on [concision](https://owl.purdue.edu/owl/general_writing/academic_writing/conciseness/index.html) for examples of “wordy vs. concise” sentences. + + - Avoid phrasing that adds little useful information for the reader, such as ending sentences with “…and more.” For example: + + - **Original:** ”Base and leading builders are hosting a global hackathon with dedicated tracks like payments, discovery, social, gaming, **and more**. + + - **Edited:** ”Base and leading builders are hosting a global hackathon dedicated to bringing the world onchain.” + +- **Tips for Improving Flow** + + - Avoid [sentence fragments](https://owl.purdue.edu/owl/general_writing/mechanics/sentence_fragments.html). + + - [Vary](https://owl.purdue.edu/owl/general_writing/academic_writing/sentence_variety/index.html) sentence structure, rhythm, opening words, and length. + +## Nuances + +**Capitalization** + +- In general, follow the [Purdue OWL](https://owl.purdue.edu/owl/general_writing/mechanics/help_with_capitals.html) guidelines for capitalization. + +- For headlines, use title case, not sentence case. + + - Example: [Onchain Summer II is Coming](https://base.mirror.xyz/HoH9cZVi8CMdvxVUNjvOzceUPVQcVZvvkf8ZbCOVOco) + +**Punctuation** + +- [Oxford Comma](https://thewritelife.com/is-the-oxford-comma-necessary/) - Base uses the **Oxford comma**. For example: + + - ❌ apples, oranges and bananas (no Oxford comma) - Do not use this style. + + - ✅ apples, oranges\*\*,\*\* and bananas (Oxford comma) - Use this style. + +- **Em Dashes** - Write em dashes as ( — ). Add spaces on both sides. For example: + + - **Em dash:** “Facilitators accept responsibility to move groups through an agenda, ensure adherence to mutually agreed-upon process mechanics, and — if necessary — suggest alternates or additional discussion.” + + - Consult [Merriam-Webster](https://www.merriam-webster.com/words-at-play/em-dash-en-dash-how-to-use) for general guidance on em dashes. + +- **Ampersands** - Use ampersands only in business names (e.g., “Tiffany\&Co.”) and common abbreviations such as “B\&B” or “R\&D.” Avoid using ampersands as a substitute for the word “and.” + +- **Parentheticals** - [Where to place that period](https://style.mla.org/the-placement-of-a-comma-or-period-after-a-quotation)? As per [Typos of the NYT](https://twitter.com/nyttypos/status/1599500874354954240): “When a sentence ends with a parenthetical, the sentence's period goes outside the parentheses (unless the entire sentence is parenthetical).” + +- **Colons and Semicolons** - For lists included as part of the text, use semicolons as separators when at least one of the list items contains a comma. Otherwise, use commas. + +**Numbers, Dates, and Times** + +- **Basics** - Consult the [Purdue OWL](https://owl.purdue.edu/owl/general_writing/grammar/writing_numbers.html) for basic guidelines. + +- **Numerals** - Write out numerals 0 through 9 as words: zero, one, two, three, etc. + + - Exception: Write 1-for-1, not one-for-one. + + - Write numerals 10 and above as Arabic numerals: 10, 59, 100, 9888, etc. + + - Abbreviate 10,000 and above with a K instead of using a comma. For example: write 100,000 as 100K. Abbreviate 1,000,000 and above with an M. Abbreviate 1,000,000,000 and above with a B. + +- **Dates** - Write dates (e.g., in blog post titles and images) as “September **2**, 2022” (or in shortened form as "Sep. 2, 2022") rather than “September **2nd**, 2022.” + +- **Time Spans** - Write full-year ranges of time as “2009—2022” with an em-dash and no spaces. + +- **Decades** - Write out the first reference to a decade as “1960s” and abbreviate subsequent instances as “60s” (no apostrophe). + +- **Clock Times** - When referring to the time, always reference both the period of day and time zone, with the period lowercase and the time zone uppercase. Do not use a space between the numeral and period of day, and then use a space for the time zone: “7am ET”, “1:30am PT” etc. When not referencing a specific location, default to PT. + +- **Software Versioning Prefixes** - Base uses lowercase version number prefixes for software (v1, v1.5, v2.6.4, etc.) rather than uppercase (V1, V1.5, V2.6.4, etc.) While there is no fixed standard, most software versioning at a low level uses Semantic Versioning Specification, aka [semver](https://semver.org/). + +This document has been remixed in part from the open-source Editorial Style Guide by [Danica Swanson](https://warpcast.com/danicaswanson) (for [Starbased](https://starbased.notion.site/Starbased-f8659abc78ad4f2095ed01bc88cca519)). From eff769b389c71ca827b6a94cfd752b4c02065bcb Mon Sep 17 00:00:00 2001 From: wbnns Date: Wed, 31 Jul 2024 01:39:06 +0000 Subject: [PATCH 2/3] fix(readme): Formatting --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index aee234e..071ea35 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ # Base brand-kit -This repo contains a [brand guide](guides/brand-guide.pdf) with fonts and logos as well as an [editorial style guide](guides/editorial-style-guide.md) for the Base. +This repo contains [brand](guides/brand-guide.pdf) and [editorial style](guides/editorial-style-guide.md) guides for Base. Base is a secure, low-cost, developer-friendly Ethereum L2 built to bring the next billion users onchain. It's built on Optimism’s open-source [OP Stack](https://stack.optimism.io/). From 98450e696dd18864436492db4dde446bbd79d13b Mon Sep 17 00:00:00 2001 From: wbnns Date: Wed, 31 Jul 2024 01:43:46 +0000 Subject: [PATCH 3/3] fix(editorial style guide): Spacing --- guides/editorial-style-guide.md | 50 --------------------------------- 1 file changed, 50 deletions(-) diff --git a/guides/editorial-style-guide.md b/guides/editorial-style-guide.md index ff3f83d..4cba92e 100644 --- a/guides/editorial-style-guide.md +++ b/guides/editorial-style-guide.md @@ -3,9 +3,7 @@ This is the Base Editorial Style Guide, which exists to: - Ensure a baseline level of quality and consistency across all media types - - Keep all contributors on the same page about editorial standards - - Align all communications from Base tonally ## About Base @@ -15,11 +13,8 @@ Base is an Ethereum Layer 2 (L2) network offering a secure, low-cost, developer- ## Critical Style Conventions - Write ‘Base’, not BASE, Base Chain, or Base Network - - Use the word ‘onchain’ instead of ‘web3’ or ‘crypto’ - - Use technical terms sparingly, and when you do, work to explain them in full - - When referring to price, use ETH and not USD ## Writing Guidelines @@ -55,37 +50,23 @@ Don't assume reader familiarity with crypto concepts. Use analogies and examples **Voice** - Progressive and future-thinking - - Conversational and human - - Direct (e.g., using "offers" over "that aims to offer") - - Optimistic but realistic (not overly idealistic) - - Appreciative (not prideful) - - Witty - - Championing of builders - - Relatable (using cultural references familiar to the audience) **Tone** - Brief and punchy, with clarity and impact - - Avoids of overly technical jargon or corporate talk - - Acknowledges challenges directly but remains solutions-oriented - - Not too casual, but still conversational - - Provides unique, thought-provoking insights - - Engages in trending topics wisely (and rarely) - - Offers compelling reasons to return through memorable and engaging content - - Minimal use of emojis (one at most) Here’s an example of writing that feels appropriate in both tone and voice: @@ -95,9 +76,7 @@ Here’s an example of writing that feels appropriate in both tone and voice: **More on tone and voice** - [Tone in Writing: A Simple Guide](https://jerryjenkins.com/tone-in-writing/) - ”**…voice is _what_ you say, and tone is _how_ you say it.**” - - [A Word About Style, Voice, and Tone](https://www.umgc.edu/current-students/learning-resources/writing-center/online-guide-to-writing/tutorial/chapter3/ch3-21.html) - “When you hear an author talking inside your head, “voice” is what that author sounds like. \[…] You can develop your own voice in your writing by paying special attention to rhythm, diction, and punctuation.” - - [Point of View](https://www.merriam-webster.com/words-at-play/point-of-view-first-second-third-person-difference) - First, second, or third person? Omniscient, limited, or objective? Check for consistency. ## Clarity, Concision, and Flow @@ -107,31 +86,21 @@ Here’s an example of writing that feels appropriate in both tone and voice: - **Tips for Improving Clarity** - [Sentence Clarity](https://owl.purdue.edu/owl/general_writing/mechanics/sentence_clarity.html) - Strategies for improving sentence clarity include using transitional words, properly placing subordinate clauses, and choosing action verbs over ‘be’ verbs (e.g. _is_, _are_). - - [Plain Style](https://owl.purdue.edu/owl/general_writing/writing_style/plain_style%20.html) - Because we specialize in reducing complex topics into concise summaries that are digestible to the average user, Base encourages contributors to write in plain style. For example: opt for simple words like _use_ rather than _utilize_. - - **Passive and Active Voice** - Base prefers active voice. Sometimes [passive voice can be rhetorically effective](https://owl.purdue.edu/owl/general_writing/academic_writing/active_and_passive_voice/choosing_passive_voice.html), but in most cases contributors should [change passive to active voice](https://owl.purdue.edu/owl/general_writing/academic_writing/active_and_passive_voice/changing_passive_to_active_voice.html). For example: - - **Original:** “Experiences that are sticky, that make it easy for anyone to get started, and that offer a seamless user experience that abstracts onchain complexity as much as possible are what we’re looking for.” (passive) - - **Edited:** “We’re looking for experiences that make it easy for anyone to get started and offer a seamless user experience that abstracts complexity as much as possible.” (active) - **Tips for Improving Concision** - Avoid redundancies. When in doubt, opt for two shorter sentences over one longer one. The [Hemingway App](https://hemingwayapp.com/) can point out areas for improvement. - - Consult the Purdue OWL page on [concision](https://owl.purdue.edu/owl/general_writing/academic_writing/conciseness/index.html) for examples of “wordy vs. concise” sentences. - - Avoid phrasing that adds little useful information for the reader, such as ending sentences with “…and more.” For example: - - **Original:** ”Base and leading builders are hosting a global hackathon with dedicated tracks like payments, discovery, social, gaming, **and more**. - - **Edited:** ”Base and leading builders are hosting a global hackathon dedicated to bringing the world onchain.” - **Tips for Improving Flow** - - Avoid [sentence fragments](https://owl.purdue.edu/owl/general_writing/mechanics/sentence_fragments.html). - - [Vary](https://owl.purdue.edu/owl/general_writing/academic_writing/sentence_variety/index.html) sentence structure, rhythm, opening words, and length. ## Nuances @@ -139,51 +108,32 @@ Here’s an example of writing that feels appropriate in both tone and voice: **Capitalization** - In general, follow the [Purdue OWL](https://owl.purdue.edu/owl/general_writing/mechanics/help_with_capitals.html) guidelines for capitalization. - - For headlines, use title case, not sentence case. - - Example: [Onchain Summer II is Coming](https://base.mirror.xyz/HoH9cZVi8CMdvxVUNjvOzceUPVQcVZvvkf8ZbCOVOco) **Punctuation** - [Oxford Comma](https://thewritelife.com/is-the-oxford-comma-necessary/) - Base uses the **Oxford comma**. For example: - - ❌ apples, oranges and bananas (no Oxford comma) - Do not use this style. - - ✅ apples, oranges\*\*,\*\* and bananas (Oxford comma) - Use this style. - - **Em Dashes** - Write em dashes as ( — ). Add spaces on both sides. For example: - - **Em dash:** “Facilitators accept responsibility to move groups through an agenda, ensure adherence to mutually agreed-upon process mechanics, and — if necessary — suggest alternates or additional discussion.” - - Consult [Merriam-Webster](https://www.merriam-webster.com/words-at-play/em-dash-en-dash-how-to-use) for general guidance on em dashes. - - **Ampersands** - Use ampersands only in business names (e.g., “Tiffany\&Co.”) and common abbreviations such as “B\&B” or “R\&D.” Avoid using ampersands as a substitute for the word “and.” - - **Parentheticals** - [Where to place that period](https://style.mla.org/the-placement-of-a-comma-or-period-after-a-quotation)? As per [Typos of the NYT](https://twitter.com/nyttypos/status/1599500874354954240): “When a sentence ends with a parenthetical, the sentence's period goes outside the parentheses (unless the entire sentence is parenthetical).” - - **Colons and Semicolons** - For lists included as part of the text, use semicolons as separators when at least one of the list items contains a comma. Otherwise, use commas. **Numbers, Dates, and Times** - **Basics** - Consult the [Purdue OWL](https://owl.purdue.edu/owl/general_writing/grammar/writing_numbers.html) for basic guidelines. - - **Numerals** - Write out numerals 0 through 9 as words: zero, one, two, three, etc. - - Exception: Write 1-for-1, not one-for-one. - - Write numerals 10 and above as Arabic numerals: 10, 59, 100, 9888, etc. - - Abbreviate 10,000 and above with a K instead of using a comma. For example: write 100,000 as 100K. Abbreviate 1,000,000 and above with an M. Abbreviate 1,000,000,000 and above with a B. - - **Dates** - Write dates (e.g., in blog post titles and images) as “September **2**, 2022” (or in shortened form as "Sep. 2, 2022") rather than “September **2nd**, 2022.” - - **Time Spans** - Write full-year ranges of time as “2009—2022” with an em-dash and no spaces. - - **Decades** - Write out the first reference to a decade as “1960s” and abbreviate subsequent instances as “60s” (no apostrophe). - - **Clock Times** - When referring to the time, always reference both the period of day and time zone, with the period lowercase and the time zone uppercase. Do not use a space between the numeral and period of day, and then use a space for the time zone: “7am ET”, “1:30am PT” etc. When not referencing a specific location, default to PT. - - **Software Versioning Prefixes** - Base uses lowercase version number prefixes for software (v1, v1.5, v2.6.4, etc.) rather than uppercase (V1, V1.5, V2.6.4, etc.) While there is no fixed standard, most software versioning at a low level uses Semantic Versioning Specification, aka [semver](https://semver.org/). This document has been remixed in part from the open-source Editorial Style Guide by [Danica Swanson](https://warpcast.com/danicaswanson) (for [Starbased](https://starbased.notion.site/Starbased-f8659abc78ad4f2095ed01bc88cca519)).