[Docs] Adding Error messages and minor changes in existing files

general/contentguidelines.md

@@ -7,8 +7,10 @@ tags:
   - UX Writing
 ---
 
-The Moodle content guidelines are for UX writers, copywriters, marketers, developers, translators, and anyone else writing for Moodle.
+The Moodle content guidelines are for UX writers, copywriters, marketers, developers, translators, and anyone else writing for Moodle. By following these guidelines, you can help ensure that we're effective at communicating key messages to our users, and that we maintain consistency across all parts of the Moodle experience.
 
-These guidelines provide recommendations on how to write effective, consistent, and reliable content for Moodle's products.
+- If you're writing content for the Moodle interface, such as confirmation messages or error messages, check out the  [**Product writing guidelines**](./category/product-writing-guidelines). They provide recommendations on how to write effective, consistent, and reliable content for Moodle's products.
 
-By following these guidelines, you can help ensure that we're effective at communicating key messages to our users, and that we maintain consistency across all parts of the Moodle experience.
+- The [**Style guide**](./contentguidelines/styleguide) is part of the Moodle™ brand guidelines and represents Moodle's values, personality and principles.
+
+If you have feedback on the guidelines or would like to suggest a specific area of content for us to focus on, please join the our [Product writing guidelines discussion](https://moodle.org/mod/forum/discuss.php?d=451533).

general/contentguidelines/01-productwriting/confirm-msg.md

@@ -125,21 +125,28 @@ Calls to action (CTAs) should be clear and simple, and offer a straightforward w
 <ValidExample title="Do">
 
 **Delete downloaded data?**  
-Cancel | Delete
+Cancel | **Delete**
 
 </ValidExample>
 
 <InvalidExample title="Don't">
 
 **Delete downloaded data?**  
-Cancel | Continue
+Cancel | **Continue**
 
 </InvalidExample>
 
+<ValidExample title="Do">
+
+**Log out from this device?**  
+Cancel | **Log out**
+
+</ValidExample>
+
 <InvalidExample title="Don't">
 
-**Delete downloaded data?**  
-No | Yes
+**Log out from this device?**  
+No | **Ok**
 
 </InvalidExample>
 
@@ -159,6 +166,13 @@ Cancel | **Continue**
 
 </InvalidExample>
 
+<ValidExample title="Don't">
+
+**Delete** tool?  
+Cancel | **Delete**
+
+</ValidExample>
+
 <InvalidExample title="Don't">
 
 **Delete** tool?  

general/contentguidelines/01-productwriting/errormsg.md

@@ -0,0 +1,168 @@
+---
+title: Error messages
+sidebar_position: 4
+tags:
+- Content style guide
+- UX Writing
+---
+import {ValidExample, InvalidExample } from '@site/src/components';
+
+Error messages describe issues that stop users from finishing a task, or the system from functioning properly. A good error message explains what happened, the reason why it happened, and what the user can do to move forward. They may even provide a way forward in the call to action.
+
+## Related components
+
+[HTML modal](https://componentlibrary.moodle.com/admin/tool/componentlibrary/docspage.php/moodle/components/dom-modal/)
+
+[Notification](https://componentlibrary.moodle.com/admin/tool/componentlibrary/docspage.php/moodle/components/notifications/)
+
+## Basic guidelines
+
+- Keep language clear and concise, and avoid jargon and technical terms.
+- Explain what happened and the reason it happened, but focus on how users can move forward.
+- Give users an error code only in cases where the error needs to be solved by a developer.
+
+## Content
+
+The structure and content of error messages will depend on the component you choose.
+
+### Title
+
+The title of your error message should be understandable on its own.
+
+Keep it short and concise.
+
+<ValidExample title="Do">
+
+Your email is missing the '@' symbol.
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+The email address doesn't match the required format. Please use a standard email format including the '@' symbol.
+
+</InvalidExample>
+
+Be specific.
+
+<ValidExample title="Do">
+
+The file is too large.
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+Coudn't upload file.
+
+</InvalidExample>
+
+<ValidExample title="Do">
+
+Your storage is full.
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+Something went wrong.
+
+</InvalidExample>
+
+Explain what happened clearly.
+
+<ValidExample title="Do">
+
+Your file was not saved.
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+There was a problem saving your file.
+
+</InvalidExample>
+
+Avoid jargon and technical terms.
+
+<ValidExample title="Do">
+
+Unable to log in.
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+Authentication error.
+
+</InvalidExample>
+
+### Description
+
+The description gives users additional information about the error and, when possible, lets them know what they can do to move forward.
+
+- Add details about the cause of the error if they can help users understand how they can avoid a similar problem in the future.
+
+- Provide a link to supporting content only when it truly helps solve the problem.
+
+- If you don't know the reason for an error, avoid making things up. Simply state that something went wrong.
+
+- If users can't solve the problem themselves, let them know what next step they should take, such as contacting their site admin.
+
+- If trying again later is a likely solution, let people know how much later: a few minutes, a few hours, etc.
+
+- When a solution can't be offered to the user, such as in cases where the error is caused by a third party, it's important to clearly explain what happened. This will help the user understand the issue and may enable them to troubleshoot the problem on their own.
+
+Use clear language, add details that can help users avoid the error in the future, and provide a solution:
+
+<ValidExample title="Do">
+
+Grade can't be negative. Adjust it to be 0 or higher.
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+Grade must be greater than or equal to zero.
+
+</InvalidExample>
+
+Don't blame the user for user-generated errors:
+
+<ValidExample title="Do">
+
+Password can't be blank.
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+You didn't type a password.
+
+</InvalidExample>
+
+### Call to action
+
+Having a call to action depends on the component you choose.
+
+When possible, provide users with a contextually relevant action that can help them solve the problem, e.g. 'Go to settings' or 'Contact support'.
+
+If you use an HTML modal to display an error message, always provide an option to dismiss the modal.
+
+Use CTA to provide users with a posssible solution:
+
+<ValidExample title="Do">
+
+**Your device is offline**  
+Download failed because you're not connected to the internet.  
+Ok | Go to settings
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+**Your device is offline**  
+Download failed because you're not connected to the internet.  
+Ok | Cancel
+
+</InvalidExample>

general/contentguidelines/01-productwriting/success-msg.md

@@ -84,8 +84,6 @@ The preset has been successfully applied.
 
 </InvalidExample>
 
-Don't repeat information from the title.
-
 <ValidExample title="Do">
 
 Message sent.

general/contentguidelines/02-styleguide/01-voice/contentprinciples.md

@@ -102,7 +102,7 @@ We write with accessibility, inclusivity and diversity in mind. That's why we av
 
 - 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*.
+- Unnecessarily gendered words, for example: Say *people* or *humanity* instead of *mankind*. Say *chairperson* or *chair* 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

general/contentguidelines/02-styleguide/grammar.md

@@ -68,11 +68,9 @@ tags:
 
 ## Dates, numbers and currencies
 
-### Dates, months, and years
-
-- For short dates, use DD/MM/YYYY without any leading zeros.
+The Moodle software allows users to customise their dates, time and numbers format to their own region and preferences. This section covers the way in which we write dates, numbers and currencies outside of the software.
 
-> Example: 21/12/1975 or 21/3/2020
+### Dates, months, and years
 
 - For long dates, use DD Month YYYY without any leading zeros.
 
@@ -84,15 +82,25 @@ tags:
 
 - For days of the week, use the following abbreviations: Mon, Tues, Weds, Thurs, Fri, Sat, Sun.
 
+- Try to avoid short dates; but if you use them, use DD/MM/YYYY without any leading zeros.
+
+> Example: 21/12/1975 or 21/3/2020
+
 ### Time and time zones
 
-- Write 'am' and 'pm' always in lowercase, with no space before them and with no periods between the letters.
+- Write 'am' and 'pm' always in lowercase, with a nonbreaking space (&nbsp) before them and with no periods between the letters.
 
-> Example: 2:00pm, not 2:00 pm
+> Example: 2:00 pm, not 2:00pm
 
 - For times on the hour, include minutes.
 
-> Example: 6:00pm, not 6pm
+> Example: 6:00 pm, not 6 pm
+
+- Use the 12-hour or 24-hour system depending on the audience you're writing for. If you're writing for a global audience, use the 24-hour format as it's more clear and consistent.
+
+- If you're writing about a specific time that affects people worldwide (for example, down time for a site or a deadline for a contest), always include the name of the time zone. Or, even better, include more than one time zone.
+
+> Example: 'The contest will close at 4:00 pm AWST / 10:00 am CEST' and not 'The contest will close at 4:00 pm'.
 
 ### Numbers, fractions, and units
 
@@ -101,15 +109,16 @@ tags:
 > 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
+- For units of measure, use lowercase letters and a nonbreaking space (&nbsp) before the unit.
 
-> Example: 121km, not 121 km.
+> Example: 121 km, not 121km.
 
 - When you write a decimal, include a leading zero before the decimal point.
 
@@ -133,6 +142,6 @@ tags:
 ## Emojis
 
 - Emojis can make your writing more fun, but don't go overboard with them :wink:.
-- Don't use negative emojis, such as 😡 😒 🤢 👹 ☠️
+- Be mindful when using emojis that might convey negative connotations or meanings, such as 😡 😒 🤢 👹 ☠️.
 
-<!-- cspell:ignore ALLCAPS Matias -->
+<!-- cspell:ignore ALLCAPS Matias -->