diff --git a/guides/editorial-style-guide.md b/guides/editorial-style-guide.md index 6ee3c24..c785cc1 100644 --- a/guides/editorial-style-guide.md +++ b/guides/editorial-style-guide.md @@ -49,7 +49,7 @@ Don't assume reader familiarity with crypto concepts. Use analogies and examples ## 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 +> ”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** @@ -85,7 +85,7 @@ Here’s an example of writing that feels appropriate in both tone and voice: ## 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) +> “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** @@ -93,7 +93,7 @@ Here’s an example of writing that feels appropriate in both tone and voice: - [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) + - **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** @@ -101,7 +101,7 @@ Here’s an example of writing that feels appropriate in both tone and voice: - 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.” + - **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). @@ -131,7 +131,7 @@ Here’s an example of writing that feels appropriate in both tone and voice: - **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. + - Exceptions: Write 1-for-1, not one-for-one. When naming something you can use the roman numerals (e.g. Onchain Summer II) - 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.” @@ -139,5 +139,6 @@ Here’s an example of writing that feels appropriate in both tone and voice: - **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/). +- **Tabs or spaces?** - we use tabs, because it's faster to press tab than space 2 times 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)).