[docs] Content style guide

general/contentstyleguide.md

@@ -0,0 +1,12 @@
+---
+title: The Moodle content style guide
+sidebar_label: Content style guide
+sidebar_position: 1
+tags:
+  - Content style guide
+  - UX Writing
+---
+
+The Moodle content style guide is for UX writers, copywriters, marketers, developers, translators, and anyone else writing for Moodle.
+
+We use this guide to help us create a clear and consistent approach to the content we produce: from our website, marketing, and communications to the actual text in Moodle products.

general/contentstyleguide/01-voice/_category_.yml

@@ -0,0 +1,3 @@
+label: Voice and tone
+link:
+  type: generated-index

general/contentstyleguide/01-voice/contentprinciples.md

@@ -0,0 +1,103 @@
+---
+title: Content principles
+sidebar_position: 2
+tags:
+  - Content style guide
+  - UX Writing
+---
+
+import {ValidExample, InvalidExample } from '@site/src/components';
+
+Our content principles help us understand and reinforce our personality, tone and voice. They also help us provide a consistent experience across all our products, services output and any other way we interact with people.
+
+With everything we write, we aim to:
+
+**Empower** our users to achieve their goals.<br/>
+**Guide** them to make the most out of our products and services.<br/>
+**Educate** them by giving them the exact information they need, plus opportunities to learn more.<br/>
+**Respect** our users, their sensitivity, and time by showing integrity and not patronising them.
+
+To achieve this, we follow these principles:
+
+### Keep it simple
+
+We write in English for a global audience, and want to make our content accessible to everyone.
+
+* Use short sentences and everyday words that our users understand and use.
+* Keep your words direct and to the point.
+* Avoid jargon and idioms that may be difficult to understand with no context. 	
+* Make instructions clear, actionable and concise.
+
+### Be relevant
+Communicate the correct details for a specific situation and no more. Get rid of complicated words and excess information. When we help users focus on the task at hand, they feel safe and empowered.
+
+### Be positive
+Tell people what they can or should do instead of what they can’t or shouldn't do. If you see lots of 'can’t' or 'don’t', you may be using negative language.
+
+<ValidExample title="Do">
+
+To complete this section, submit your final assignment.
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+You can't complete this section until you submit your final assignment.
+
+</InvalidExample>
+
+### Use active voice
+Active voice eliminates ambiguity.
+
+<ValidExample title="Do">
+
+Teachers can set a deadline.
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+A deadline can be set by teachers.
+
+</InvalidExample>
+
+### Limit your exclamation points
+*When everything is exciting, nothing is exciting*. We save exclamation points for key moments in the user journey; for example when we welcome them on board one of our products for the first time.
+
+### Spell out acronyms the first time you use them
+Example: Branded Moodle App (BMA)
+
+### Use sentence case
+Use capital letters only at the beginning of sentences and for proper nouns. For headings, subheadings and calls to action, we use sentence case and not Title Case.
+
+<ValidExample title="Do">
+
+Read the full article.
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+Read the Full Article.
+
+</InvalidExample>
+
+### Follow the rules of UK/Australian English
+Although we have global headquarters, we default to UK/Australian spelling. (Except for communications from Moodle US, which use American spelling to suit their market.)
+
+### Avoid regionally specific date formats
+Don't use 13/02/2022 or 02/13/2022. To avoid confusion, write the date as 13 February 2022.
+
+### Words and phrases to avoid
+We write with accessibility, inclusivity and diversity in mind. That’s why we avoid:
+
+* Language that reinforces racial, ethnic or religious stereotypes, for example:  Use *allowlist* and *denylist* instead of *whitelist* and *blacklist*.
+* Ableist language, for example: Say *amazing*, *awesome*, *shocking* or *intense* instead of *insane* or *crazy*.  Say *final check* instead of *sanity check*.
+* Unnecessarily gendered words, for example: Say *people* or *humanity* instead of *mankind*. Say *chairperson* instead of *chairman*.
+* Figures of speech that refer to war or violence, for example: Say *try* instead of *take a shot*. Say *near miss* instead of *dodged bullet*
+
+### Use diverse examples
+If you’re inventing people or situations, choose different genders and ages. Don’t stick to English names.
+
+### Ask for a quick review
+If English is not your first language and you feel unsure about the clarity of something you’re writing, reach out to a native English speaking team member for support.

general/contentstyleguide/01-voice/values.md

@@ -0,0 +1,18 @@
+---
+title: Values, personality and principles
+sidebar_position: 1
+tags:
+  - Content style guide
+  - UX Writing
+---
+Our values are the core Moodle beliefs and unify everything we do. Our personality is influenced by our values and describes the set of characteristics that we attribute to Moodle. Or, to put it another way, it’s how we describe Moodle as if Moodle were a person. Understanding our brand personality is essential because it helps us connect more deeply to our brand identity and fosters brand loyalty.  
+
+Finally, our principles are a set of guiding behaviours that inform everything we do, irrespective of who we're talking to, shifting goals, strategies, activities, or the competitive market.
+
+| Value | Personality |  Principle |
+|------------------------------|-------------------------------------------------------------------|---------------------------------|
+| **Education**<br/>Education is the foundation of making the world a better place. We're always learning, improving how we learn, and helping those around us to learn and teach. | We're **knowledgeable** but also curious and enquiring. | We embrace a culture of humility and continuous learning and encourage each other's development. |
+| **Openness**<br/>We strive to be open in our goals, tools, processes and results as much as is practical. We encourage team members and our community to communicate freely both internally and externally. We promote accessibility and embrace international cultures across all our products. | We're **approachable**, broad-minded and strive to be impartial and unbiased. | We're mindful of different lived experiences and treat everyone with the common decency we all deserve and expect. |
+| **Respectful**<br/>We treat everyone with respect and sensitivity, recognising the importance of their contributions: team members, customers, partners, suppliers and competitors. | We're **egalitarian**, compassionate, supportive and courteous. | We act in a humanitarian, trustworthy manner that earns the respect of each other, our community and our customers. |
+| **Integrity**<br/>We employ the highest ethical standards, demonstrating honesty and fairness in every action we take. | We're **sincere** and principled. | We're true to our word and accept accountability for our actions. |
+| **Innovation**<br/>We encourage a progressive culture of data-driven experimentation and research, where entrepreneurship and prudent risk-taking are encouraged, rewarded and incorporated. | We're **creative**, inventive and reflective. | We're passionate and enjoy working collaboratively across boundaries, challenging the status quo and driving solutions. |

general/contentstyleguide/01-voice/voiceandtone.md

@@ -0,0 +1,52 @@
+---
+title: Voice and tone
+sidebar_position: 4
+tags:
+  - Content style guide
+  - UX Writing
+---
+
+Our voice and tone are how we express ourselves.
+
+
+Our voice is who we are: it represents our personality and our principles, and it’s constant throughout the Moodle experience. Moodle’s voice is human - it’s approachable, sincere, knowledgeable and respectful.
+
+
+While we only have one voice, we have different tones that allow us to adapt our voice to different situations: different audiences, contexts, or emotional states of the people we are engaging.
+
+
+For example, our friendly voice may have a reassuring tone when a user is doing something critical like backing up data. But it can have a more playful tone when we congratulate a user for accomplishing something.
+
+
+Below are some examples of how our tone flexes in different situations:
+
+#### Press release
+
+Audience: Public, external stakeholders, staff, media
+Tone: Direct and impartial
+> Today, Moodle announced the release of Moodle LMS 4.0 and a radically improved user experience for Moodle’s 300 million learners worldwide. Informed by an extensive discovery and consultation process…
+
+
+
+#### Social post
+Audience: Team members, partners, community, potential users
+Tone: Warm, friendly, engaging, conversational and informative
+> Meet Moodle HQ in Brisbane! Will you join us at MoodleMoot Australia to improve your skills, meet the community and learn from experts?
+
+
+#### Blog post / Newsletter
+Audience: Team members, partners, community, potential users
+Tone: Informative, helpful, conversational, educational
+> Moodle HQ will be at ALTC to meet members of the education community face-to-face and share ideas about how our open source platform can help you achieve your goals.  
+
+
+#### Success stories
+Audience: Team members, partners, community, potential users
+Tone: Engaging, inspiring, emotive
+> The school district is part of a growing, vibrant area that traces its history back to the 1800s when the first school in Dearborn was just a simple, one-room log cabin.
+
+
+#### In-product copy
+Audience: Users
+Tone: Helpful, informative and conversational
+> Looks like you typed the wrong site address. Check for typos and try again.

general/contentstyleguide/01-voice/whoweare.md

@@ -0,0 +1,108 @@
+---
+title: Who we are, who we aren't
+sidebar_position: 3
+tags:
+  - Content style guide
+  - UX Writing
+---
+import {ValidExample, InvalidExample } from '@site/src/components';
+
+When representing Moodle either as a team member or as part of our community, it’s essential to reflect on who Moodle is and who we aren't. Avoid confrontation in our written, verbal, or other forms of communication.
+
+We're **approachable**, not **hostile**.
+<ValidExample title="Do">
+
+Thanks for alerting me to this project. Why don’t we have a meeting to discuss how we can support each other?
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+Sorry, that’s not my remit, so you’ll need to talk to someone else about that.
+
+</InvalidExample>
+
+We're **knowledgable**, not **patronising**
+
+<ValidExample title="Do">
+
+Thanks for your input. We value your perspective. To explain our approach…
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+What you have suggested is incorrect and doesn’t reflect best practice….
+
+</InvalidExample>
+
+
+We're **egalitarian**, not **arrogant**.
+
+<ValidExample title="Do">
+
+Thanks for your enquiry. Could you please answer a few short questions so I can make sure we connect you with the best representative?
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+Can you please tell us what your requirements are for us to determine whether we can help you.
+
+</InvalidExample>
+
+<ValidExample title="Do">
+
+Thanks for reaching out. Unfortunately, we can’t help you, but I recommend you consider a MoodleCloud package, which…
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+I’m sorry, we don’t work with small budgets.
+
+</InvalidExample>
+
+We're **sincere**, not **flippant**.
+
+<ValidExample title="Do">
+
+Thanks for your suggestions. I had some ideas I didn’t communicate when I briefed you on this task. Can we have a quick meeting to discuss this?
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+Please change the colour. It doesn’t work.
+
+</InvalidExample>
+
+
+We're **creative**, not **silly**.
+
+<ValidExample title="Do">
+
+3 reasons to take the stage and make an impact at MoodleMoot Global 2022!
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+It’s super easy to impress other Moodlers at MoodleMoot Global!
+
+</InvalidExample>
+
+
+We're **supportive**, not **opposing**.  
+
+<ValidExample title="Do">
+
+Thanks for your query regarding delivering our Developer course in German. I will reach out to my colleagues at Moodle Academy to discuss this and get back to you in the next 48 hours with a response.
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+IMO, we should deliver our courses in German as we have lots of users there.
+
+</InvalidExample>

general/contentstyleguide/02-style/_category_.yml

@@ -0,0 +1,3 @@
+label: Style
+link:
+  type: generated-index