agaric/documentation
10
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update information about Voice and try to fix bullets

Browse source
This commit is contained in:
benjamin melançon 2022-02-09 22:18:15 -05:00
parent e7e281628d
commit f73aff65f0
1 changed files with 19 additions and 25 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

44
content-style-guide.md
View file

@ -4,25 +4,19 @@ Please reference this styleguide when writing for Agaric to keep our communicati
## Summary
Good content is:
Good content is authentic, useful, and appropriate to its context.
* Authentic, useful, and appropriate
Agaric's voice is straightforward, bold, and irreverant.
Agaric's voice is:
* Confident but not arrogant
* Upbeat but not in denial
* Unconstrained but not incomprehensible
* Open, curious, eclectic; but not scattered
### Writing about people
We write and build apps with a person-first perspective. Being aware of the impact of language is one way for us to live out our [values](values).
* Do not reference age or ability unless it is relevant to what you're writing.
* Avoid gendered language and use the singular they.
* When writing about a person, use their preferred pronouns; if you do not know those, use their name.
* Related resource: [The Conscious Style Guide](https://consciousstyleguide.com/).
* Do not reference age or ability unless it is immediately relevant.
* Avoid gendered language and use the singular they.
* When writing about a person, use their preferred pronouns; if you do not know those, use their name.
* Related resource: [The Conscious Style Guide](https://consciousstyleguide.com/).
### Grammar and mechanics
@ -31,16 +25,16 @@ Some people will read every word you write. Others will just scan. Help everyone
Focus your message, and create a hierarchy of information. Lead with the main point or the most important content.
* Use active voice and positive language.
* Use short words and sentences.
* Avoid unnecessary modifiers.
* Use specific examples.
* Avoid vague language.
* Be consistent. Adhere to the copy patterns and style points outlined in this guide.
* Do not use contractions as they cheapen the content and provide difficulty for readers of other languages.
* Use the serial comma. Otherwise, use common sense. (Also known as the Oxford comma, it helps clarify when items in a list of three, four, or more things are their own items.)
* Do not use underline for emphasis, and do not use any combination of italic, bold, caps, and underline.
* When in doubt, read your writing out loud.
* Use active voice and positive language.
* Use short words and sentences.
* Avoid unnecessary modifiers.
* Use specific examples.
* Avoid vague language.
* Be consistent. Adhere to the copy patterns and style points outlined in this guide.
* Do not use contractions as they cheapen the content and provide difficulty for readers of other languages.
* Use the serial comma. Otherwise, use common sense. (Also known as the Oxford comma, it helps clarify when items in a list of three, four, or more things are their own items.)
* Do not use underline for emphasis, and do not use any combination of italic, bold, caps, and underline.
* When in doubt, read your writing out loud.
Many of these repeat or reinforce George Orwell's six rules from his essay "Politics and the English Language" (1946), and it is worth keeping all of them in mind, especially the last:
@ -96,9 +90,9 @@ We strive to have the same voice all the time, but our tone changes to suit the
Agaric's voice is:
* Straightforward and earnest
* Unafraid of bold and even visionary calls to action
*
* Straightforward and earnest.
* Unafraid of bold and even visionary calls to action.
* Irreverant; the human condition is too serious to take anything too seriously.
### Tone