Skip to content

Commit 317c848

Browse files
sarjonasarjona
authored
Merge pull request #730 from juliavs85/prodwriting
[docs] Product writing guidelines
2 parents a92bbd2 + f3c7f12 commit 317c848

File tree

3 files changed

+311
-0
lines changed

3 files changed

+311
-0
lines changed

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

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
---
2+
title: Confirmation messages
3+
sidebar_position: 2
4+
tags:
5+
- Content style guide
6+
- UX Writing
7+
---
8+
import {ValidExample, InvalidExample } from '@site/src/components';
9+
10+
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.
11+
12+
Clear and concise confirmation messages help people feel more confident and in control of their actions within the Moodle products.
13+
14+
## Related components
15+
16+
[HTML modal](https://componentlibrary.moodle.com/admin/tool/componentlibrary/docspage.php/moodle/components/dom-modal/)
17+
18+
## Basic guidelines
19+
20+
- Address a single task.
21+
- Ask a clear, specific question.
22+
- Provide clear options to either confirm or cancel the action.
23+
- Explain the consequences of the action so people can make an informed decision.
24+
25+
## Content
26+
27+
### Title
28+
29+
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.
30+
31+
<ValidExample title="Do">
32+
33+
**Remove grade?**
34+
35+
</ValidExample>
36+
37+
<InvalidExample title="Don't">
38+
39+
**Confirm action?**
40+
41+
</InvalidExample>
42+
43+
Ask a clear, unambiguous question.
44+
45+
<ValidExample title="Do">
46+
47+
**Delete question?**
48+
49+
</ValidExample>
50+
51+
<InvalidExample title="Don't">
52+
53+
**Confirmation**
54+
55+
</InvalidExample>
56+
57+
<ValidExample title="Do">
58+
59+
**Send notification?**
60+
61+
</ValidExample>
62+
63+
<InvalidExample title="Don't">
64+
65+
**Warning**
66+
67+
</InvalidExample>
68+
69+
Don't include articles like 'a', 'an' or 'the', so that the question is short and easy to scan.
70+
71+
### Description
72+
73+
The description should explain the consequences of the action and share additional details that enable people to make a confident decision.
74+
75+
<ValidExample title="Do">
76+
77+
**Delete entry?**
78+
This will delete the entry 'My first blog post'.
79+
80+
</ValidExample>
81+
82+
<InvalidExample title="Don't">
83+
84+
**Delete entry?**
85+
Are you sure you want to delete the blog post?
86+
87+
</InvalidExample>
88+
89+
Don't repeat information from the title.
90+
91+
<ValidExample title="Do">
92+
93+
**Remove account 'Barbara Gardner'?**
94+
This account and its data on the site [site name] will be removed from the app on this device.
95+
96+
</ValidExample>
97+
98+
<InvalidExample title="Don't">
99+
100+
**Remove account 'Barbara Gardner'?**
101+
Are you sure you want to remove this account?
102+
103+
</InvalidExample>
104+
105+
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.
106+
107+
<ValidExample title="Do">
108+
109+
**Delete tool?**
110+
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?
111+
112+
</ValidExample>
113+
114+
<InvalidExample title="Don't">
115+
116+
**Delete activity?**
117+
Are you sure you want to delete the activity?
118+
119+
</InvalidExample>
120+
121+
### Calls to action
122+
123+
Calls to action (CTAs) should be clear and simple, and offer a straightforward way out.
124+
125+
<ValidExample title="Do">
126+
127+
**Delete downloaded data?**
128+
Cancel | Delete
129+
130+
</ValidExample>
131+
132+
<InvalidExample title="Don't">
133+
134+
**Delete downloaded data?**
135+
Cancel | Continue
136+
137+
</InvalidExample>
138+
139+
<InvalidExample title="Don't">
140+
141+
**Delete downloaded data?**
142+
No | Yes
143+
144+
</InvalidExample>
145+
146+
Use the same verb in both the title and the confirmation button to make the content more scannable and summarise outcomes.
147+
148+
<ValidExample title="Do">
149+
150+
**Move** selected activities?
151+
Cancel | **Move**
152+
153+
</ValidExample>
154+
155+
<InvalidExample title="Don't">
156+
157+
**Move** selected activities?
158+
Cancel | **Continue**
159+
160+
</InvalidExample>
161+
162+
<InvalidExample title="Don't">
163+
164+
**Delete** tool?
165+
Cancel | **Remove**
166+
167+
</InvalidExample>
168+
169+
Avoid 'cancelling cancellations'
170+
171+
<ValidExample title="Do">
172+
173+
**Cancel booking?**
174+
Keep my booking | Cancel booking
175+
176+
</ValidExample>
177+
178+
<InvalidExample title="Don't">
179+
180+
**Cancel subscription?**
181+
Cancel | Confirm cancellation
182+
183+
</InvalidExample>

‎general/contentstyleguide/03-productwriting/index.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
title: Product writing guidelines
3+
tags:
4+
- Content style guide
5+
- UX Writing
6+
---
7+
import {ValidExample, InvalidExample } from '@site/src/components';
8+
9+
These guidelines provide recommendations on how to write effective, consistent, and reliable content for Moodle's products.
10+
11+
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

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
---
2+
title: Success messages
3+
sidebar_position: 3
4+
tags:
5+
- Content style guide
6+
- UX Writing
7+
---
8+
import {ValidExample, InvalidExample } from '@site/src/components';
9+
10+
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.
11+
12+
## Related components
13+
14+
[Notification](https://componentlibrary.moodle.com/admin/tool/componentlibrary/docspage.php/moodle/components/notifications/)
15+
16+
## Basic guidelines
17+
18+
- Keep success messages short and scannable.
19+
- Focus on what the user has achieved or the system has completed.
20+
- Avoid technical jargon.
21+
- Add a full stop at the end of success messages.
22+
23+
## Content
24+
25+
### Message
26+
27+
Use the short form of passive instead of the full form.
28+
29+
<ValidExample title="Do">
30+
31+
Changes saved.
32+
33+
</ValidExample>
34+
35+
<InvalidExample title="Don't">
36+
37+
Your changes have been saved.
38+
39+
</InvalidExample>
40+
41+
<InvalidExample title="Don't">
42+
43+
Changes were saved.
44+
45+
</InvalidExample>
46+
47+
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.
48+
49+
<ValidExample title="Do">
50+
51+
Course created.
52+
53+
</ValidExample>
54+
55+
<InvalidExample title="Don't">
56+
57+
The course has been added to your site.
58+
59+
</InvalidExample>
60+
61+
<ValidExample title="Do">
62+
63+
Tool deleted.
64+
65+
</ValidExample>
66+
67+
<InvalidExample title="Don't">
68+
69+
The tool was removed.
70+
71+
</InvalidExample>
72+
73+
In general, avoid expressions like 'successfully' or 'successful'.
74+
75+
<ValidExample title="Do">
76+
77+
Preset applied.
78+
79+
</ValidExample>
80+
81+
<InvalidExample title="Don't">
82+
83+
The preset has been successfully applied.
84+
85+
</InvalidExample>
86+
87+
Don't repeat information from the title.
88+
89+
<ValidExample title="Do">
90+
91+
Message sent.
92+
93+
</ValidExample>
94+
95+
<InvalidExample title="Don't">
96+
97+
Message delivery successful.
98+
99+
</InvalidExample>
100+
101+
### Calls to action
102+
103+
Use a call to action only if there are any next steps that users can take. For example, seeing something new they have created.
104+
105+
Keep calls to action as short and actionable as you can.
106+
107+
<ValidExample title="Do">
108+
109+
Message posted. You have 30 minutes to edit it. **See post**.
110+
111+
</ValidExample>
112+
113+
<InvalidExample title="Don't">
114+
115+
Your message has been posted successfully. You have 30 mins to make any changes to it.
116+
117+
</InvalidExample>

0 commit comments

Comments
 (0)