Merge pull request #800 from WestpacGEL/content-copywriting-guides-kate

Content copywriting guides kate
WestpacGEL · May 28, 2024 · a23ec8a · a23ec8a
2 parents bd4691f + 7e9b207
commit a23ec8a
Show file tree

Hide file tree

Showing 6 changed files with 74 additions and 45 deletions.
diff --git a/...rc/content/design-system/accessibility/design-system-accessibility/accessibilityDemo.mdoc b/...rc/content/design-system/accessibility/design-system-accessibility/accessibilityDemo.mdoc
diff --git a/...m/accessibility/design-system-accessibility/design/inclusive-content-writing/content.mdoc b/...m/accessibility/design-system-accessibility/design/inclusive-content-writing/content.mdoc
@@ -1,3 +1,6 @@
-As well as offering simple products, we need to ensure we communicate their specifics in a clear and inclusive way. Complicated terminology can be appropriate for a certain audience, especially when talking about products and services that are specific to customers in more specialised fields. But in general our products and services are for the whole community, so we should ensure that content is easily readable, and if there are situations where that is not possible then we need to use supplemental content to clarify it. According to WCAG ‘Supplemental content is required when text demands reading ability more advanced than the lower secondary education level—that is, more than nine years of school.’
+Writing in a clear, simple way promotes equal access to information, creating a society where no one is left behind.  As a guide, our content needs to be understood by a 13 year old to cater for people who have a basic understanding of legal and financial language and who use English as a second language, as well as those with an intellectual or learning disability. Some common things to consider when writing for a diverse audience include:
 
-The most common form of supplemental content in a digital context would be the ‘Help text’ you find associated with forms and calculators.
+- spelling [acronyms](/content/guidelines/acronym) in full when they’re first mentioned.
+- writing [link copy that provides context](/content/guidelines/hyperlinks-email-addresses) instead of using ‘click here’.
+- [avoid using terms that assumes the way a person interacts with something](/content/guidelines/calls-to-action-ctas), for example, ‘walk’, ‘simply’, ‘see’ or ‘watch’.
+  For more information on writing simply and inclusively, check out the [Writing for Digital Guidelines](/content/writing-for-digital).
diff --git a/...accessibility/design-system-accessibility/design/principles-of-accessibility/content.mdoc b/...accessibility/design-system-accessibility/design/principles-of-accessibility/content.mdoc
@@ -1,21 +1,21 @@
 The following comes from the [W3.org](https://www.w3.org/) website, it explains the four principles of accessibility that the Web Contact Accessibility Guidelines (WCAG) and Success Criteria are organised around:
 
-> _**1\. Perceivable**_ _- Information and user interface components must be presentable to users in ways they can perceive._
->
-> _This means that users must be able to perceive the information being presented (it can't be invisible to all of their senses)_
->
-> _**2\. Operable**_ _- User interface components and navigation must be operable._
->
-> _This means that users must be able to operate the interface (the interface cannot require interaction that a user cannot perform)_
->
-> _**3\. Understandable**_ _\- Information and the operation of user interface must be understandable._
->
-> _This means that users must be able to understand the information as well as the operation of the user interface (the content or operation cannot be beyond their understanding)_
->
-> _**4\. Robust**_ _- Content must be robust enough that it can be interpreted reliably by a wide variety of user agents, including assistive technologies._
->
-> _This means that users must be able to access the content as technologies advance (as technologies and user agents evolve, the content should remain accessible)_
->
-> _If any of these are not true, users with disabilities will not be able to use the Web._
+> ***1. Perceivable*** *- Information and user interface components must be presentable to users in ways they can perceive.*
+> 
+> *This means that users must be able to perceive the information being presented (it can't be invisible to all of their senses)*
+> 
+> ***2. Operable*** *- User interface components and navigation must be operable.*
+> 
+> *This means that users must be able to operate the interface (the interface cannot require interaction that a user cannot perform)*
+> 
+> ***3. Understandable*** *- Information and the operation of user interface must be understandable.*
+> 
+> *This means that users must be able to understand the information as well as the operation of the user interface (the content or operation cannot be beyond their understanding)*
+> 
+> ***4. Robust*** *- Content must be robust enough that it can be interpreted reliably by a wide variety of user agents, including assistive technologies.*
+> 
+> *This means that users must be able to access the content as technologies advance (as technologies and user agents evolve, the content should remain accessible)*
+> 
+> *If any of these are not true, users with disabilities will not be able to use the Web.*
 
 See [www.w3.org/WAI/WCAG21/Understanding/intro](https://www.w3.org/WAI/WCAG21/Understanding/intro) for the entire article.
diff --git a/apps/site/src/content/design-system/accessibility/design-system-accessibility/index.yaml b/apps/site/src/content/design-system/accessibility/design-system-accessibility/index.yaml
@@ -4,23 +4,34 @@ description: >-
   be diligent and aware of the impacts the decisions we make have at all stages
   of product delivery. The following areas need to be considered when designing
   for accessibility and inclusion.
+namedExport:
+  discriminant: false
+excludeFromNavbar: false
 design:
   - title:
       name: Principles of accessibility
       slug: principles-of-accessibility
+    noTitle: false
   - title:
       name: Inclusive product design
       slug: inclusive-product-design
+    noTitle: false
   - title:
       name: Inclusive content writing
       slug: inclusive-content-writing
+    noTitle: false
   - title:
       name: Accessible interfaces
       slug: accessible-interfaces
+    noTitle: false
   - title:
       name: Accessibility testing
       slug: accessibility-testing
+    noTitle: false
   - title:
       name: Deprecated components
       slug: deprecated-components
+    noTitle: false
 accessibility: []
+relatedComponents: []
+code: []
diff --git a/...design-system/content/guidelines/calls-to-action-ctas/design/calls-to-action/content.mdoc b/...design-system/content/guidelines/calls-to-action-ctas/design/calls-to-action/content.mdoc
@@ -2,9 +2,12 @@ CTAs should be short and action-orientated – using buttons and hyperlinked tex
 
 For example:
 
-{% designSystemBodyImage alt="Two examples of calls to action that are short and action oriented." src="https://res.cloudinary.com/westpac-gel/image/upload/v1667894142/cla7x3vj6001ef58icgubfckf.png" title="Use short, action oriented calls to action" /%}
+{% designSystemBodyImage
+   title="Use short, action oriented calls to action"
+   src="https://res.cloudinary.com/westpac-gel/image/upload/v1667894142/cla7x3vj6001ef58icgubfckf.png"
+   alt="Two examples of calls to action that are short and action oriented." /%}
 
-_Note: No full stops in CTAs but fine to use question marks._
+*Note: No full stops in CTAs but fine to use question marks.*
 
 ---
 
@@ -19,20 +22,17 @@ Hyperlinks must be underlined unless they’re standalone text links, in which c
 </div>
 ```
 
-Instead of using generic CTAs such as ‘Find out more’ and ‘Learn more’ – try to be contextual for accessibility and best practice (SEO & UX).
-
-However, when space is limited, try CTAs such as ‘Tell me more’ or ‘Show me how’ instead of ‘Find out more’ and ‘Learn more’.
+Contextual links are best for accessibility and best practice (SEO & UX). Try to avoid using generic CTAs such as ‘Find out more’ and ‘Learn more’.
 
 ```jsx
 <div>
   <h4 className="typography-body-10 text-muted mb-3">FOR EXAMPLE:</h4>
   <p className="typography-body-10  mb-2 ml-3">Find out more about balance transfers</p>
   <p className="typography-body-10  mb-6 ml-3">
-    To learn more about whether Online Banking is right for you, see our Online Banking Terms & Conditions for more
-    information.
+To learn more about whether Online Banking is right for you, check out our Online Banking Terms & Conditions for more information.
   </p>
   <p className="typography-body-10 mb-2 ml-4">
-    <span className="text-success font-bold">Do:</span> Submit application
+    <span className="text-success font-bold">Do:</span> Return to Online Banking
   </p>
   <p className="typography-body-10 ml-4">
     <span className="text-danger font-bold">Don't:</span> Finish
@@ -42,35 +42,53 @@ However, when space is limited, try CTAs such as ‘Tell me more’ or ‘Show m
 
 ---
 
-Try to avoid overt navigation instructions, e.g. ‘Click the link below to start the survey’ or ‘call the number below’
+CTAs with specific descriptions are more accessible, SEO-friendly, and contribute to a better user experience. So, instead of saying ‘Find out more’ or ‘Learn more’, try using CTAs like ‘Explore accounts’ and ‘Discover EFTPOS’
 
 ```jsx
 <div>
   <h4 className="typography-body-10 text-muted mb-3">FOR EXAMPLE:</h4>
-  <p className="typography-body-10  mb-2 ml-3">
-    Use a CTA button or hyperlink that says{' '}
-    <Link href="#" type="inline">
-      Start survey now
-    </Link>
+  <p className="typography-body-10  mb-2 ml-3">When space is limited, it’s ok to use ‘Find out more’ and ‘Learn more’. Remember to keep accessibility in mind, not everyone consumes content in a visual way.</p>
+
+  <p className="typography-body-10 mb-2 ml-4">
+    <span className="text-success font-bold">Do:</span> Show me how, Check out, Review, Refer to, Visit a branch
+  </p>
+  <p className="typography-body-10 ml-4">
+    <span className="text-danger font-bold">Don't:</span> View, See, Watch, Walk into a branch, Watch or listen to
   </p>
-  <p className="typography-body-10  mb-2 ml-3">
-    Call us on{' '}
-    <Link href="#" type="inline">
-      13 20 32
-    </Link>
+</div>
+```
+
+---
+
+Avoid directional navigation instructions, e.g. Instead, be clear on what you want the reader to do.
+
+```jsx
+<div>
+  <h4 className="typography-body-10 text-muted mb-3">FOR EXAMPLE:</h4>
+   <p className="typography-body-10 mb-2 ml-4">
+    <span className="text-danger font-bold">Don't:</span> Click the link below to start the survey
+  </p>
+  <p className="typography-body-10 mb-3 ml-4">
+    <span className="text-success font-bold">Do:</span> Use a CTA button or hyperlink that says ‘Start survey now’
+  </p>
+   <p className="typography-body-10 mb-2 ml-4">
+    <span className="text-danger font-bold">Don't:</span> Call the number above
+  </p>
+  <p className="typography-body-10 ml-4">
+    <span className="text-success font-bold">Do:</span> Call us on 13 20 32
   </p>
 </div>
 ```
 
 ---
 
-Keep verbs appropriate to the device type.
+There are different ways a person could use a device e.g. someone who doesn’t use a mouse may not ‘click’ a link. Therefore, where possible, keep verbs appropriate to the device type.
 
 ```jsx
 <div>
   <h4 className="typography-body-10 text-muted mb-3">FOR EXAMPLE:</h4>
   <p className="typography-body-10 mb-3 ml-4">
-    <span className=" font-bold">Mobile:</span> Go to, tap, swipe, scroll, select, choose
+    <span className=" font-bold">Mobile:</span> Go to, select, swipe*, scroll, choose
   </p>
   <p className="typography-body-10 mb-3 ml-4">
     <span className=" font-bold">Desktop:</span> Go to, select, scroll, choose
@@ -79,11 +97,7 @@ Keep verbs appropriate to the device type.
     <span className=" font-bold">Cross-device:</span> Go to, select, scroll, choose
   </p>
   <p className="typography-body-10 text-muted mb-3 italic">
-    Note: ‘Click’ doesn’t adhere to the{' '}
-    <Link href="https://www.w3.org/WAI/tips/writing/" type="inline">
-      Accessibility & Inclusion Guidelines
-    </Link>
-    .
+*Use ‘swipe’ only if it’s not possible to use other verbs to describe the action.
   </p>
 </div>
 ```

diff --git a/apps/site/src/content/design-system/content/guidelines/calls-to-action-ctas/index.yaml b/apps/site/src/content/design-system/content/guidelines/calls-to-action-ctas/index.yaml
@@ -2,6 +2,7 @@ name: Calls to action (CTAs)
 description: Calls to action are used to get a person to perform an instruction.
 namedExport:
   discriminant: false
+excludeFromNavbar: false
 design:
   - title:
       name: Calls to action