Better doc styling, tabs or spaces, cites #22
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
🟡 Heimdall Review Status
|
T-Damer
commented
Aug 5, 2024
| @@ -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 | |||
There was a problem hiding this comment.
We used \~ below in citations, so I decided to use it here as well + I think it's better to use blockquote (or > in markdown) to outline citations
There was a problem hiding this comment.
We may also want to add a link to Shelby Crawford
T-Damer
commented
Aug 5, 2024
|
|
||
| - **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) | ||
| - **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) |
There was a problem hiding this comment.
I think it's easier to compare stuff when it's aligned like:
- Original
- Edited
Not like
- Original
- Edited
T-Damer
commented
Aug 5, 2024
| - 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. | ||
| - Exceptions: Write 1-for-1, not one-for-one. When naming something you can use the roman numerals (e.g. Onchain Summer II) |
There was a problem hiding this comment.
It's described in Purdue OWL, but probably worth mentioning in the doc?
T-Damer
commented
Aug 5, 2024
| - 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/). | ||
| - **Tabs or spaces?** - we use tabs, because it's faster to press <kbd>tab</kbd> than <kbd>space</kbd> 2 times |
There was a problem hiding this comment.
We may start WW3 with this, but I used tabs when edited this doc
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.