diff --git a/general/contentstyleguide.md b/general/contentstyleguide.md new file mode 100644 index 0000000000..2c114259e4 --- /dev/null +++ b/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. diff --git a/general/contentstyleguide/01-voice/_category_.yml b/general/contentstyleguide/01-voice/_category_.yml new file mode 100644 index 0000000000..49d1d5de6f --- /dev/null +++ b/general/contentstyleguide/01-voice/_category_.yml @@ -0,0 +1,3 @@ +label: Voice and tone +link: + type: generated-index diff --git a/general/contentstyleguide/01-voice/contentprinciples.md b/general/contentstyleguide/01-voice/contentprinciples.md new file mode 100644 index 0000000000..1116bf0b29 --- /dev/null +++ b/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.
+**Guide** them to make the most out of our products and services.
+**Educate** them by giving them the exact information they need, plus opportunities to learn more.
+**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. + + + +To complete this section, submit your final assignment. + + + + + +You can't complete this section until you submit your final assignment. + + + +### Use active voice +Active voice eliminates ambiguity. + + + +Teachers can set a deadline. + + + + + +A deadline can be set by teachers. + + + +### 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. + + + +Read the full article. + + + + + +Read the Full Article. + + + +### 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. diff --git a/general/contentstyleguide/01-voice/values.md b/general/contentstyleguide/01-voice/values.md new file mode 100644 index 0000000000..af730ba78c --- /dev/null +++ b/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**
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**
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**
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**
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**
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. | diff --git a/general/contentstyleguide/01-voice/voiceandtone.md b/general/contentstyleguide/01-voice/voiceandtone.md new file mode 100644 index 0000000000..dec87a8ac7 --- /dev/null +++ b/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. diff --git a/general/contentstyleguide/01-voice/whoweare.md b/general/contentstyleguide/01-voice/whoweare.md new file mode 100644 index 0000000000..edb638e28a --- /dev/null +++ b/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**. + + +Thanks for alerting me to this project. Why don’t we have a meeting to discuss how we can support each other? + + + + + +Sorry, that’s not my remit, so you’ll need to talk to someone else about that. + + + +We're **knowledgable**, not **patronising** + + + +Thanks for your input. We value your perspective. To explain our approach… + + + + + +What you have suggested is incorrect and doesn’t reflect best practice…. + + + + +We're **egalitarian**, not **arrogant**. + + + +Thanks for your enquiry. Could you please answer a few short questions so I can make sure we connect you with the best representative? + + + + + +Can you please tell us what your requirements are for us to determine whether we can help you. + + + + + +Thanks for reaching out. Unfortunately, we can’t help you, but I recommend you consider a MoodleCloud package, which… + + + + + +I’m sorry, we don’t work with small budgets. + + + +We're **sincere**, not **flippant**. + + + +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? + + + + + +Please change the colour. It doesn’t work. + + + + +We're **creative**, not **silly**. + + + +3 reasons to take the stage and make an impact at MoodleMoot Global 2022! + + + + + +It’s super easy to impress other Moodlers at MoodleMoot Global! + + + + +We're **supportive**, not **opposing**. + + + +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. + + + + + +IMO, we should deliver our courses in German as we have lots of users there. + + diff --git a/general/contentstyleguide/02-style/_category_.yml b/general/contentstyleguide/02-style/_category_.yml new file mode 100644 index 0000000000..acd6bcda8c --- /dev/null +++ b/general/contentstyleguide/02-style/_category_.yml @@ -0,0 +1,3 @@ +label: Style +link: + type: generated-index diff --git a/general/contentstyleguide/02-style/grammar.md b/general/contentstyleguide/02-style/grammar.md new file mode 100644 index 0000000000..a171526190 --- /dev/null +++ b/general/contentstyleguide/02-style/grammar.md @@ -0,0 +1,109 @@ +--- +title: Grammar and mechanics +sidebar_position: 1 +tags: + - Content style guide + - UX Writing +--- + +## Capitalisation + +* Capitalise proper nouns: names of people, places, and organisations. Capitalise also geographic terms such as countries and cities, and historic episodes and events. +* Use sentence case for all headlines and headings. +* Don't use ALLCAPS unless you're writing an acronym. +* For email addresses and website URLs, use all lowercase. + + +## Punctuation + +### Apostrophes +* To make a possessive from a noun that ends in -s, use only an apostrophe (no s).
+> Example: Matias' Moodle site runs on 4.3. + +* Pluralise acronyms by adding -s. +> Example: These URLs are secure. + +### Ampersands +* Don't use an ampersand (&) or a plus sign (+) to mean 'and', unless it's used in a brand name. + +### Contractions +* Use contractions for common phrases, such as 'don't' or 'can't'.

+> Example: These passwords don't match. +> Example: Students can't see who marked their work. + +### Commas +* When writing lists, always use the Oxford comma.

+> Example: This includes user ID, role, and course ID. + +### Dashes and hyphens +* Use an em dash (—) with spaces before and after to offset an aside, and use an en dash (–) to connect a range of numbers or dates.

+> Example: The newest version of Moodle LMS —released last month— has had 200,000 downloads. +> There will be 200-250 attendees. + +### Exclamation marks +* Save exclamation marks for key moments in the user journey. +* Don't use more than one exclamation mark. + +### Percentages +* With numbers, use '%' instead of the word 'percent'.

+> Example: You've completed 89% of the course. + +### Periods +* Don't user periods in country acronyms.

+> Example: Their headquarters are located in New York, USA. + +## Dates, numbers and currencies + +### Dates, months, and years +* For short dates, use DD/MM/YYYY without any leading zeros.
+> Example: 21/12/1975 or 21/3/2020 + +* For long dates, use DD Month YYYY without any leading zeros.
+> Example: 21 December 1975 + +* If you include the day of the week in a date, add a comma after the day.
+> Example: Friday, December 21 + +* For days of the week, use the following abbreviations: Mon, Tues, Weds, Thurs, Fri, Sat, Sun. + + +### Time and time zones +* Write 'am' and 'pm' always in lowercase, with no space before them and with no periods between the letters.
+> Example: 2:00pm, not 2:00 pm + +* For times on the hour, include minutes.
+> Example: 6:00pm, not 6pm + + +### Numbers, fractions, and units +* Spell out numbers if they're the first word in a sentence.

+> Example: Three days left to get early bird tickets. + + +* To separate thousands and millions, use commas. +* To indicate decimal points, use periods.
+> Example: 1,000 (one thousand); 3.14 (three point one four) + +* Always use a country code with phone numbers. + +* For units of measure, use lowercase letters and don't leave a space before the unit
+> Example: 121km, not 121 km. + +* When you write a decimal, include a leading zero before the decimal point.
+> Example: 0.75, not .75. + + +### Currencies and money +* For currencies, put the symbol before the amount, with no space in between.
+> Example: €300, not 300€ + +* Don't use periods in currency abbreviations.
+> Example: AUD, not A.U.D + +* Spell out thousand, million, billion, and trillion in full.
+> Example: 3 million users, not 3M users. +> Example 10 thousand resources, not 10K resources. + +## Emojis +* Emojis can make your writing more fun, but don't go overboard with them :wink:. +* Don't use negative emojis, such as 😡 😒 🤢 👹 ☠️ diff --git a/general/contentstyleguide/02-style/translation.md b/general/contentstyleguide/02-style/translation.md new file mode 100644 index 0000000000..9e2da26eb3 --- /dev/null +++ b/general/contentstyleguide/02-style/translation.md @@ -0,0 +1,124 @@ +--- +title: How we write - a focus on translation +sidebar_position: 3 +tags: + - Content style guide + - UX Writing +--- + +import { CodeBlock, TabItem, Tabs, ValidExample, InvalidExample } from '@site/src/components'; + +### 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. + +### Use active voice +Active voice eliminates ambiguity. + + + + +Teachers can set a deadline. +You should... +Your site is... + + + + + + + +A deadline can be set by teachers. +It is recommended to… +It has been detected that your site is … + + + + +### Spell out acronyms the first time you use them +Example: Branded Moodle App (BMA) + +### Use capital letters at the beginning of sentences and for proper nouns only. +For titles, subtitles and calls to action, we use sentence case and not Title Case. + + + + +Read the full article. + + + + + + + +Read the Full Article. + + + + + +### 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. + + + +### Be mindful of length +Translated text is often longer or shorter than your original text in English. This is especially important when writing text for our products. If you have doubts about whether you’re compromising the layout or structure, double-check with a designer. + + + +### Avoid using flags to represent languages +Flags represent countries or regions, but not languages: some countries have multiple languages, while many languages are spoken in more than one country. Instead, use the name of the language in its native format followed by its corresponding ISO 639 abbreviation. +> Example: ‘Deutsch (de)’ for German or ‘日本語 (ja)’ for Japanese. + + +### Avoid using holiday references +Holidays are often culture-specific and referencing them can be alienating to people who don’t celebrate them. + +### Gendered pronouns +Many languages lack gender-inclusive options, like the pronoun “they” in English. When possible, don’t use gendered pronouns. Use the “you” pronoun instead of the third person “she/he”. + + +### Gendered adjectives +In many languages, nouns and adjectives are gendered, and finding gendered-inclusive options is difficult. When referring to people, try to avoid adjectives and find a different way of writing what you want to say. + + + + +Add the first entry + +When the adjective “first” refers to an object, in this case “entry”, the translator will automatically use the gender of the object. + + + + + + +Be the first student to add an entry. + +When the adjective “first” refers to a person, in this case a student, in many languages it will need a gender. The translator will have to make a difficult decision. + + +Avoid using substantivised adjectives too, as they'll also be gendered in many languages. That is, adjectives that act as nouns, for example: + + + + +Add the first entry + +When the adjective “first” refers to an object, in this case “entry”, the translator will automatically use the gender of the object. + + + + + + +Be the first to add an entry. + +The adjective "first" acts like a noun, which means it will need a gender in many languages. + diff --git a/general/contentstyleguide/02-style/wordlist.md b/general/contentstyleguide/02-style/wordlist.md new file mode 100644 index 0000000000..63ae3159a7 --- /dev/null +++ b/general/contentstyleguide/02-style/wordlist.md @@ -0,0 +1,59 @@ +--- +title: Word list +sidebar_position: 2 +tags: + - Content style guide + - UX Writing +--- + + +This word list contains guidelines on how we use specific terms at Moodle. If you can't find a word here, check [the dictionary](https://www.macmillandictionary.com/) or use the search function to see if we've addressed it somewhere else in the guide. + +|Term |Notes |Description |Do |Don’t | +|-----------------------------------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------| +|ATTO text editor | |The text editor that comes by default with Moodle. | | | +|BigBlueButton | | | | | +|Brickfield Accessibility Starter Toolkit | |This is the accessibility toolkit that comes with Moodle LMS by default. | | | +|Brickfield Education Labs | |One of our Moodle Certified Integrations. | | | +|EdTech | | | | | +|eLearning | | | | | +|HTML | | | | | +|ID | | | | | +|IntelliBoard | |One of our Moodle Certified Integrations. | | | +|Invalid |Don't use|Invalid is not an inclusive word, so try to use "wrong", or "not working" or "incorrect" instead. If possible, use not valid instead of invalid to avoid wrong machine translations. |Wrong username or password. |Invalid username or password. | +|JavaScript | | | | | +|learning management platform | |Sometimes we use this instead of "learning management system" | | | +|learning management system | |We can abbreviate this as LMS | | | +|learning platform | | | | | +|login | |Login should be one word when used as a noun. If you're using it as a verb, leave a space. |You can log in with your email and password. |Login with your email and password. | +|Moodle | |Are you talking about one of our products? If so, add the product name after Moodle: Moodle LMS, Moodle Workplace, Moodle Academy, etc. |Moodle is a great to place to work. | | +|Moodle Academy | |Moodle Academy is the learning hub for the global Moodle community. We refer to it in full and don't say "Academy" or "the Academy". | | | +|Moodle App | |Moodle App allows learners to access Moodle both online and offline from anywhere and on any device. | | | +|Moodle Certified Integration | |Software that integrates with Moodle LMS to add extra functionality. | | | +|Moodle Certified Partner | |You can use this to refer to our Moodle Certified Partners and also as an umbrella term for Moodle Certified Partners and Moodle Premium Certified Partners. | | | +|Moodle Educator Certification | | |The Moodle Educator Certification (MEC) is a certification program for educators, or learning and development professional | | +|Moodle HQ | | | | | +|Moodle HQ Marketing | | | | | +|Moodle LMS | |Moodle LMS is an open source learning management system that can be customised for any course or teaching method you choose. | | | +|Moodle LMS 4.0 | | | | | +|Moodle Partner | |If this is the first time you're mentioning this in a text or blog, use the official term Moodle Certified Partner. | | | +|Moodle Premium Certified Partner | |"Moodle" comes first in this description, not Premium Certified Moodle Partner. | | | +|Moodle Premium Certified Service Provider|Don't use|If you're referring to a Moodle Partner, use Moodle Premium Certified Partner instead. | | | +|Moodle Premium Partner | |If this is the first time you're mentioning this in a text or blog, use the official term Moodle Premium Certified Partner. | | | +|Moodle Service Providers | |This term is used to refer to Moodle HQ's service companies located in key regions (e.g. Moodle India, Moodle US). | | | +|Moodle US | |Moodle US is our services company in the US | | | +|Moodle Workplace | |Moodle Workplace is a customisable enterprise learning management platform streamlining workplace onboarding, learning, and compliance training. | | | +|moodle.com | |This is Moodle's commercial website for people to learn more about our products and services. | | | +|moodle.org | |moodle.org is our community site, where people can get involved with Moodle by contributing to the project in many different ways: support forums, translations, writing documentation. | | | +|MoodleCloud | |MoodleCloud is our off-the-shelf LMS solution that’s ready to go with Moodle’s most popular features built-in. | | | +|MoodleMoot | |MoodleMoot conferences are held around the world, with a focus on encouraging collaboration and sharing of best practices of the open source learning platform. | | | +|MoodleNet | |MoodleNet is our global network to share and curate open educational resources. | | | +|online learning | | | | | +|open source | |We don't capitalise open source | | | +|Partner | |If this is the first time you're mentioning this in a text or blog, use the official term Moodle Certified Partner. You can sparingly use 'Partner' without Moodle in front if you use the possessive article 'our'. |Our Partner in Guatemala are hosting MootGT22. | | +|Please | |Save the word "please" for when you’re asking the user to do something inconvenient or an extra effort, or in situations where our product is to blame. In calls-to-action, try to explain why the user should do something rather than saying please. E.g. "Please sign up for updates" can be "Sign up to get the latest updates" |Your device is offline. Connect to a Wi-Fi network and try again.

We couldn't fetch your information. Please log out and log in to synchronise this site.

Sign up to get the latest updates.|Please sign up for updates. | +|Safe Exam Browser (SEB) | |Safe Exam Browser (SEB) is an open source lockdown browser that allows teachers to carry out e-assessments safely. It can be abbreviated as SEB. | | | +|See | |When talking about the interface, use the words view or show instead of see (not everyone can see). | | | +|Sorry | |Use the word sorry only when something unexpected happens and our product fails to meet expectations. Apologising doesn’t help fix the problem, so we try to focus on giving the user a solution. |Only logged in users can post to this forum.

No matching results for your search. |Sorry, guests can't post to this forum.

Sorry, there are no matching results for your search.| +|WCAG 2.1 AA | |Moodle LMS follows the WCAG 2.1 AA accessibility guidelines and is certified as WCAG 2.1 AA compliant | | | +|Wi-Fi | | | | | diff --git a/sidebars/general.js b/sidebars/general.js index b741c66720..a420d6f322 100644 --- a/sidebars/general.js +++ b/sidebars/general.js @@ -152,7 +152,22 @@ const sidebars = { }, }, ], - + contentstyleguide: [ + { + label: 'Content style guide', + type: 'category', + items: [ + { + type: 'autogenerated', + dirName: 'contentstyleguide', + }, + ], + link: { + type: 'doc', + id: 'contentstyleguide', + }, + }, + ], releaseNotes: [ getReleaseNotes(), {