[docs] Product writing guidelines

general/contentstyleguide/03-productwriting/confirm-msg.md

@@ -0,0 +1,183 @@
+---
+title: Confirmation messages
+sidebar_position: 2
+tags:
+- Content style guide
+- UX Writing
+---
+import {ValidExample, InvalidExample } from '@site/src/components';
+
+Confirmation messages prompt people to confirm actions that have significant consequences or are difficult to undo. They can also help prevent errors or unexpected results by verifying user intent before proceeding with an action.
+
+Clear and concise confirmation messages help people feel more confident and in control of their actions within the Moodle products.
+
+## Related components
+
+[HTML modal](https://componentlibrary.moodle.com/admin/tool/componentlibrary/docspage.php/moodle/components/dom-modal/)
+
+## Basic guidelines
+
+- Address a single task.
+- Ask a clear, specific question.
+- Provide clear options to either confirm or cancel the action.
+- Explain the consequences of the action so people can make an informed decision.
+
+## Content
+
+### Title
+
+The title or heading of a confirmation message should focus only on one task, and mention the specific action that the user wants to perform.
+
+<ValidExample title="Do">
+
+**Remove grade?**
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+**Confirm action?**
+
+</InvalidExample>
+
+Ask a clear, unambiguous question.
+
+<ValidExample title="Do">
+
+**Delete question?**
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+**Confirmation**
+
+</InvalidExample>
+
+<ValidExample title="Do">
+
+**Send notification?**
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+**Warning**
+
+</InvalidExample>
+
+Don't include articles like 'a', 'an' or 'the', so that the question is short and easy to scan.
+
+### Description
+
+The description should explain the consequences of the action and share additional details that enable people to make a confident decision.
+
+<ValidExample title="Do">
+
+**Delete entry?**  
+This will delete the entry 'My first blog post'.
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+**Delete entry?**  
+Are you sure you want to delete the blog post?
+
+</InvalidExample>
+
+Don't repeat information from the title.
+
+<ValidExample title="Do">
+
+**Remove account 'Barbara Gardner'?**  
+This account and its data on the site [site name] will be removed from the app on this device.
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+**Remove account 'Barbara Gardner'?**  
+Are you sure you want to remove this account?
+
+</InvalidExample>
+
+Save "Are you sure?" for actions that have very serious consequences. For example, actions that could prevent a course or activity from working properly, or deleting something that can't be retrieved from the recycle bin.
+
+<ValidExample title="Do">
+
+**Delete tool?**  
+This tool is currently being used in at least one activity in your course. If you delete this tool, the activities that use it will no longer work. Are you sure you want to delete the tool?
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+**Delete activity?**  
+Are you sure you want to delete the activity?
+
+</InvalidExample>
+
+### Calls to action
+
+Calls to action (CTAs) should be clear and simple, and offer a straightforward way out.
+
+<ValidExample title="Do">
+
+**Delete downloaded data?**  
+Cancel | Delete
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+**Delete downloaded data?**  
+Cancel | Continue
+
+</InvalidExample>
+
+<InvalidExample title="Don't">
+
+**Delete downloaded data?**  
+No | Yes
+
+</InvalidExample>
+
+Use the same verb in both the title and the confirmation button to make the content more scannable and summarise outcomes.
+
+<ValidExample title="Do">
+
+**Move** selected activities?  
+Cancel | **Move**
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+**Move** selected activities?  
+Cancel | **Continue**
+
+</InvalidExample>
+
+<InvalidExample title="Don't">
+
+**Delete** tool?  
+Cancel | **Remove**
+
+</InvalidExample>
+
+Avoid 'cancelling cancellations'
+
+<ValidExample title="Do">
+
+**Cancel booking?**  
+Keep my booking | Cancel booking
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+**Cancel subscription?**  
+Cancel | Confirm cancellation
+
+</InvalidExample>

general/contentstyleguide/03-productwriting/index.md

@@ -0,0 +1,11 @@
+---
+title: Product writing guidelines
+tags:
+- Content style guide
+- UX Writing
+---
+import {ValidExample, InvalidExample } from '@site/src/components';
+
+These guidelines 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.

general/contentstyleguide/03-productwriting/success-msg.md

@@ -0,0 +1,117 @@
+---
+title: Success messages
+sidebar_position: 3
+tags:
+- Content style guide
+- UX Writing
+---
+import {ValidExample, InvalidExample } from '@site/src/components';
+
+Success messages tell users that they've completed a task or achieved a goal, or that an action within the system has been successfully completed.
+
+## Related components
+
+[Notification](https://componentlibrary.moodle.com/admin/tool/componentlibrary/docspage.php/moodle/components/notifications/)
+
+## Basic guidelines
+
+- Keep success messages short and scannable.
+- Focus on what the user has achieved or the system has completed.
+- Avoid technical jargon.
+- Add a full stop at the end of success messages.
+
+## Content
+
+### Message
+
+Use the short form of passive instead of the full form.
+
+<ValidExample title="Do">
+
+Changes saved.
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+Your changes have been saved.
+
+</InvalidExample>
+
+<InvalidExample title="Don't">
+
+Changes were saved.
+
+</InvalidExample>
+
+Use a verb that describes the action that has been completed successfully, especially if the success message is triggered by an action that the user took.
+
+<ValidExample title="Do">
+
+Course created.
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+The course has been added to your site.
+
+</InvalidExample>
+
+<ValidExample title="Do">
+
+Tool deleted.
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+The tool was removed.
+
+</InvalidExample>
+
+In general, avoid expressions like 'successfully' or 'successful'.
+
+<ValidExample title="Do">
+
+Preset applied.
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+The preset has been successfully applied.
+
+</InvalidExample>
+
+Don't repeat information from the title.
+
+<ValidExample title="Do">
+
+Message sent.
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+Message delivery successful.
+
+</InvalidExample>
+
+### Calls to action
+
+Use a call to action only if there are any next steps that users can take. For example, seeing something new they have created.
+
+Keep calls to action as short and actionable as you can.
+
+<ValidExample title="Do">
+
+Message posted. You have 30 minutes to edit it. **See post**.
+
+</ValidExample>
+
+<InvalidExample title="Don't">
+
+Your message has been posted successfully. You have 30 mins to make any changes to it.
+
+</InvalidExample>