From aac151c4bffd0804a8278ea29b7d19eef17d41f3 Mon Sep 17 00:00:00 2001 From: Anne-Sophie Dumetz Date: Tue, 6 Feb 2024 17:39:45 -0800 Subject: [PATCH 1/9] content update on Canadian Style and section 7 - removing references to Canadian Style in the intro and resources - Added section 7.2.2 -removed section 7.4 & made 7.5 the new 7.4 --- style-guide/index.md | 95 +++++++++++++++++++++++++++++--------------- 1 file changed, 64 insertions(+), 31 deletions(-) diff --git a/style-guide/index.md b/style-guide/index.md index b3570d3307..2ee28e4791 100644 --- a/style-guide/index.md +++ b/style-guide/index.md @@ -1,7 +1,7 @@ --- altLangPage: "https://conception.canada.ca/guide-redaction" date: 2017-10-05 -dateModified: 2024-01-31 +dateModified: 2024-02-07 description: "The Canada.ca Content Style Guide provides the rules to create web content that can be easily found, understood and used." title: "Canada.ca Content Style Guide" --- @@ -46,7 +46,8 @@ title: "Canada.ca Content Style Guide"

Purpose

This guide establishes the rules you must use to develop and edit English web content that will be published on a Government of Canada website. The rules are different from practices adapted to print to support principles related to accessibility, readability and usability.

The purpose of these rules is to make web content easy to find, easy to understand and easy to use for everyone, including people who have physical or cognitive disabilities.

-

The techniques described in this guide complement the rules set out in The Canadian Style. If there are conflicts between this guide and The Canadian Style or any other resource, this guide takes priority for content published online.

+

The techniques described in this guide complement the rules set out in Writing Tips Plus, a searchable tool that deals with difficult points of English grammar and punctuation, as well as other English writing conventions. + If there are conflicts between this guide, Writing Tips Plus or any other resource, this guide takes priority for content published online.

As web and language trends evolve, we'll update this guide to meet the changing needs of our audiences.

@@ -876,13 +877,16 @@ title: "Canada.ca Content Style Guide"
  • for long passages of text, such as quotations
  • in page titles
    • -

    Follow The Canadian Style's rules for applying italics for the following:

    +

    Follow Writing Tips Plus rules for applying italics for the following:

    + +

    See how the rule for bold, italics and underlining applies in French

    See how the rule for bold, italics and underlining applies in French

    +
    +
    +

    Use parentheses for contextual information

    +

    Use parentheses inside a link to add information that provides context about the linked content. Only provide necessary, contextual information to help users decide whether to proceed.

    +

    This guidance applies in the following situations:

    + + +
  • Link opens video or audio content. Specify the length of the content inside the parentheses.
    • + +
  • When more than one situation applies, include all applicable information in parentheses.
    • + +

    See how the rule for writing descriptive links applies in French

    + +
    +
    +
    +
    +

    7.3 Make sure that links work

    Make sure that your links work. Check that they take people to the correct page, which contains up-to-date information, in the appropriate official language. Links that don't work frustrate people and hurt the credibility of your content.

    @@ -2256,27 +2309,7 @@ title: "Canada.ca Content Style Guide"
    -

    7.4 Linking to non-government content

    -

    Some non-government web content isn't available in both official languages. If you're linking to external web content that isn't available in the language of the current page, say in which language(s) it is available after the link.

    -

    On English pages, write the following after a link that leads to content that isn't available in English: "(XXXX only)".

    -

    If the link leads to content only available in:

    - -

    Example of a link that leads to content only available in French

    -

    Write: Find out how to renew your French passport while abroad in Canada (French only).

    -

    See how the rule for non-government content applies in French

    - -
    -
    -
    -
    -
    -

    7.5 Linking to internal-to-government content

    +

    7.4 Linking to internal-to-government content

    In most cases, public-facing content should not link to content that is accessible only through internal government networks. Occasionally, the audience for content that is accessible to the public may be primarily internal.

    When a link leads to content available only on internal government networks, write "(accessible only on the Government of Canada network)."

    See how the rule for internal-to-government content applies in French

    @@ -2284,7 +2317,7 @@ title: "Canada.ca Content Style Guide"
  • 7.5 Créer des liens vers du contenu interne
    • -
    +
    @@ -3093,7 +3126,6 @@ title: "Canada.ca Content Style Guide"
  • Study: Literacy and numeracy among off-reserve First Nations people and Métis, 2012, Statistics Canada
  • Study: University graduates with lower levels of literacy and numeracy skills, 2012, Statistics Canada
  • TERMIUM Plus®, Translation Bureau
    • -
  • The Canadian Style, Translation Bureau
  • The Magical Number Seven, Plus or Minus Two: Some Limits on Our Capacity for Processing, George A. Miller
  • Use pair writing to collaborate with subject matter experts, Jonathan Kahn, GatherContent
  • Watch Your Punctuation Online, Search Engine People
    • @@ -3101,5 +3133,6 @@ title: "Canada.ca Content Style Guide"
  • Why Don't Screen Readers Always Read What's on the Screen?, The Deque Blog
  • Writing for the web, Nielsen Norman Group
  • Writing for the Web: Principles and Guidelines, University of Ottawa
    • +
  • Writing Tips Plus, Resource of the Language Portal of Canada, Government of Canada
    • From 1a52380fd90e8128015c5c0f024bacf50dfd59a9 Mon Sep 17 00:00:00 2001 From: Anne-Sophie Dumetz Date: Tue, 6 Feb 2024 17:54:07 -0800 Subject: [PATCH 2/9] update to writing tips link --- style-guide/index.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/style-guide/index.md b/style-guide/index.md index 2ee28e4791..331e17c09c 100644 --- a/style-guide/index.md +++ b/style-guide/index.md @@ -877,16 +877,13 @@ title: "Canada.ca Content Style Guide"
  • for long passages of text, such as quotations
  • in page titles
    • -

    Follow Writing Tips Plus rules for applying italics for the following:

    +

    Follow Writing Tips Plus rules for applying italics for the following:

    -

    See how the rule for bold, italics and underlining applies in French

    -

    See how the rule for bold, italics and underlining applies in French

  • 7.3 Make sure that links work
    • -
  • 7.4 Linking to non-government content
    • +
  • 7.4 Linking to internal-to-government content
    • From 2b35e68ce9760fd4aa08fbd8ceb35e2e29ebb739 Mon Sep 17 00:00:00 2001 From: Peter Crane Date: Thu, 8 Feb 2024 08:04:38 -0500 Subject: [PATCH 5/9] Update index.md --- style-guide/index.md | 106 +++++++++++++++++++++---------------------- 1 file changed, 51 insertions(+), 55 deletions(-) diff --git a/style-guide/index.md b/style-guide/index.md index 9c8fc1f918..8ed673ef0e 100644 --- a/style-guide/index.md +++ b/style-guide/index.md @@ -1,7 +1,7 @@ --- altLangPage: "https://conception.canada.ca/guide-redaction" date: 2017-10-05 -dateModified: 2024-02-07 +dateModified: 2024-02-08 description: "The Canada.ca Content Style Guide provides the rules to create web content that can be easily found, understood and used." title: "Canada.ca Content Style Guide" --- @@ -877,13 +877,13 @@ title: "Canada.ca Content Style Guide"
  • for long passages of text, such as quotations
  • in page titles
    • -

    Follow Writing Tips Plus rules for applying italics for the following:

    +

    Follow Writing Tips Plus rules for applying italics for the following:

    See how the rule for bold, italics and underlining applies in French

      @@ -2238,6 +2238,50 @@ title: "Canada.ca Content Style Guide"
      Instead of:

      To ensure that you are paid the maximum Employment Insurance (EI) benefit rate that you are entitled to, complete the Claimant Attestation - Highest Weeks of Insurable Earnings (Variable Best Weeks) form with the required information about your highest weeks of insurable earnings in the last 52 weeks of employment or since the start of your last claim, whichever is the shorter period of the two.

      +
      +

      Use parentheses for contextual information

      +

      Use parentheses inside a link to add information that provides context about the linked content. Only provide necessary, contextual information to help users decide whether to proceed.

      +

      This guidance applies in the following situations:

      + +

      See how the rule for writing descriptive links applies in French

      • 7.2 Rédiger des liens descriptifs
        • @@ -2246,54 +2290,6 @@ title: "Canada.ca Content Style Guide"
        -
        -
        -

        Use parentheses for contextual information

        -

        Use parentheses inside a link to add information that provides context about the linked content. Only provide necessary, contextual information to help users decide whether to proceed.

        -

        This guidance applies in the following situations:

        - - -
      • Link opens video or audio content. Specify the length of the content inside the parentheses.
        • - -
      • When more than one situation applies, include all applicable information in parentheses.
        • - -

        See how the rule for writing descriptive links applies in French

        - -
        -
        -
        -
        -

        7.3 Make sure that links work

        Make sure that your links work. Check that they take people to the correct page, which contains up-to-date information, in the appropriate official language. Links that don't work frustrate people and hurt the credibility of your content.

        From accd62c46361aefacb3d38d1da53f7db06cf0f52 Mon Sep 17 00:00:00 2001 From: Peter Crane Date: Thu, 8 Feb 2024 08:12:22 -0500 Subject: [PATCH 6/9] Update index.md --- style-guide/index.md | 168 ++++++++++++++++++++++--------------------- 1 file changed, 85 insertions(+), 83 deletions(-) diff --git a/style-guide/index.md b/style-guide/index.md index 8ed673ef0e..bc6c1029c2 100644 --- a/style-guide/index.md +++ b/style-guide/index.md @@ -2201,94 +2201,96 @@ title: "Canada.ca Content Style Guide"
        -

        7.2 Write descriptive links

        -

        A link must describe the content a person will find once they click on it. It's easier to complete a task when a link's destination matches a person's expectations.

        -

        Tips for providing useful links:

        -
          -
        • use the first words of the target page or its entire title if it's descriptive enough
          • -
        • start with keywords that accurately describe the target page if the page title isn't enough
          • -
        • make sure that all links on the same page use unique descriptive text if they link to different target pages
          • -
        • when more than one link on a web page links to the same destination page, use the same words for the hyperlink
          • -
        • describe any content that must be downloaded
          • -
        • write email addresses in full, in lower case and as active links (contact helpdesk@canada.ca)
          • -
        -

        Don't use:

        +

        7.2 Write descriptive links

        +

        A link must describe the content a person will find once they click on it. It's easier to complete a task when a link's destination matches a person's expectations.

        +

        Tips for providing useful links:

        +
          +
        • use the first words of the target page or its entire title if it's descriptive enough
          • +
        • start with keywords that accurately describe the target page if the page title isn't enough
          • +
        • make sure that all links on the same page use unique descriptive text if they link to different target pages
          • +
        • when more than one link on a web page links to the same destination page, use the same words for the hyperlink
          • +
        • describe any content that must be downloaded
          • +
        • write email addresses in full, in lower case and as active links (contact helpdesk@canada.ca)
          • +
        +

        Don't use:

        +
          +
        • the same link text to point to 2 different pages
          • +
        • vague statements such as "click here" or "read more"
          • +
        • promotional messaging that might confuse someone who is deciding whether to go to the page that is being linked to
          • +
        +
        +

        Focus on the task

        +

        When writing instructions for completing a task, sometimes you need to insert a link to guide the person to forms or other documents. Focus on the action they must perform when you create the link.

        +

        Don't repeat the name of a form or document in the steps to accomplish a task if the name isn't descriptive.

        +

        Example of the use of links that focus on the task

        +
        Write:
        +

        To get the highest Employment Insurance amount available to you:

        +
          +
        1. open the form you need to declare your income
          2. +
        2. identify your highest weeks of insurable income in the shortest period below: +
            +
          • the last 52 weeks of employment
            • +
          • since the start of your last claim
            • +
          +
          3. +
        3. return the completed form in person to the Service Canada office closest to you
          4. +
        +
        Instead of:
        +

        To ensure that you are paid the maximum Employment Insurance (EI) benefit rate that you are entitled to, complete the Claimant Attestation - Highest Weeks of Insurable Earnings (Variable Best Weeks) form with the required information about your highest weeks of insurable earnings in the last 52 weeks of employment or since the start of your last claim, whichever is the shorter period of the two.

        +
        +
        +

        Use parentheses for contextual information

        +

        Use parentheses inside a link to add information that provides context about the linked content. Only provide necessary, contextual information to help users decide whether to proceed.

        +

        This guidance applies in the following situations:

        + +
        +

        See how the rule for writing descriptive links applies in French

        + +
        +
        +

        7.3 Make sure that links work

        From 3bcd6bb7a2ae812fa070723e70517ca5d99de4cb Mon Sep 17 00:00:00 2001 From: Peter Crane Date: Thu, 8 Feb 2024 08:16:34 -0500 Subject: [PATCH 7/9] Update index.md --- style-guide/index.md | 171 ++++++++++++++++++++++--------------------- 1 file changed, 86 insertions(+), 85 deletions(-) diff --git a/style-guide/index.md b/style-guide/index.md index bc6c1029c2..62336e3c48 100644 --- a/style-guide/index.md +++ b/style-guide/index.md @@ -2201,96 +2201,97 @@ title: "Canada.ca Content Style Guide"
        -

        7.2 Write descriptive links

        -

        A link must describe the content a person will find once they click on it. It's easier to complete a task when a link's destination matches a person's expectations.

        -

        Tips for providing useful links:

        -
          -
        • use the first words of the target page or its entire title if it's descriptive enough
          • -
        • start with keywords that accurately describe the target page if the page title isn't enough
          • -
        • make sure that all links on the same page use unique descriptive text if they link to different target pages
          • -
        • when more than one link on a web page links to the same destination page, use the same words for the hyperlink
          • -
        • describe any content that must be downloaded
          • -
        • write email addresses in full, in lower case and as active links (contact helpdesk@canada.ca)
          • -
        -

        Don't use:

        -
          -
        • the same link text to point to 2 different pages
          • -
        • vague statements such as "click here" or "read more"
          • -
        • promotional messaging that might confuse someone who is deciding whether to go to the page that is being linked to
          • -
        -
        -

        Focus on the task

        -

        When writing instructions for completing a task, sometimes you need to insert a link to guide the person to forms or other documents. Focus on the action they must perform when you create the link.

        -

        Don't repeat the name of a form or document in the steps to accomplish a task if the name isn't descriptive.

        -

        Example of the use of links that focus on the task

        -
        Write:
        -

        To get the highest Employment Insurance amount available to you:

        -
          -
        1. open the form you need to declare your income
          2. -
        2. identify your highest weeks of insurable income in the shortest period below: -
            -
          • the last 52 weeks of employment
            • -
          • since the start of your last claim
            • -
          -
          3. -
        3. return the completed form in person to the Service Canada office closest to you
          4. -
        -
        Instead of:
        -

        To ensure that you are paid the maximum Employment Insurance (EI) benefit rate that you are entitled to, complete the Claimant Attestation - Highest Weeks of Insurable Earnings (Variable Best Weeks) form with the required information about your highest weeks of insurable earnings in the last 52 weeks of employment or since the start of your last claim, whichever is the shorter period of the two.

        -
        -
        -

        Use parentheses for contextual information

        -

        Use parentheses inside a link to add information that provides context about the linked content. Only provide necessary, contextual information to help users decide whether to proceed.

        -

        This guidance applies in the following situations:

        -
          -
        • Link is to a downloadable document. Make sure to include the file type and size in the parentheses: +

          7.2 Write descriptive links

          +

          A link must describe the content a person will find once they click on it. It's easier to complete a task when a link's destination matches a person's expectations.

          +

          Tips for providing useful links:

            -
          • Example: State of the Canadian Space Sector Report (PDF, 4.35 MB)
            • +
          • use the first words of the target page or its entire title if it's descriptive enough
            • +
          • start with keywords that accurately describe the target page if the page title isn't enough
            • +
          • make sure that all links on the same page use unique descriptive text if they link to different target pages
            • +
          • when more than one link on a web page links to the same destination page, use the same words for the hyperlink
            • +
          • describe any content that must be downloaded
            • +
          • write email addresses in full, in lower case and as active links (contact helpdesk@canada.ca)
          -
          • -
        • -

          Link to external content is in a different language.

          -

          Some non-government web content isn't available in both official languages. If you're linking to external web content that isn't available in the language of the current page, say in which language(s) it is available after the link.

          -
            -
          • Add parentheses inside the link and specify the language of the linked content, formatted as (Language X only).
            • -
          • Do not translate the title of the linked content.
            • -
          • Ensure its language is indicated in the link’s code.
            • -
          -

          On an English page, write:

          -
        -

        See how the rule for writing descriptive links applies in French

        - -
        -
        -
        +
        +

        See how the rule for writing descriptive links applies in French

        + +
        +
        +

        7.3 Make sure that links work

        From 45cf999a25e3d6994590d1ab0ee60bc87e84dcc5 Mon Sep 17 00:00:00 2001 From: Peter Crane Date: Thu, 8 Feb 2024 08:21:41 -0500 Subject: [PATCH 8/9] Update index.md --- style-guide/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/style-guide/index.md b/style-guide/index.md index 62336e3c48..13615f2662 100644 --- a/style-guide/index.md +++ b/style-guide/index.md @@ -2256,7 +2256,7 @@ title: "Canada.ca Content Style Guide"
      • Do not translate the title of the linked content.
      • Ensure its language is indicated in the link’s code.
      -

      On an English page, write:

      +

      On an English page, write:

    -

    Follow the same structure on French-language pages linking to English content:

    +

    Follow the same structure on French-language pages linking to English content:

    From 443addca849a15794e50c2a373a93ef7748ec9bb Mon Sep 17 00:00:00 2001 From: donohuech <118768603+donohuech@users.noreply.github.com> Date: Thu, 8 Feb 2024 10:52:14 -0500 Subject: [PATCH 9/9] Update index.md --- style-guide/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/style-guide/index.md b/style-guide/index.md index 13615f2662..3772878454 100644 --- a/style-guide/index.md +++ b/style-guide/index.md @@ -2158,7 +2158,7 @@ title: "Canada.ca Content Style Guide"
  • 7.2 Write descriptive links
  • 7.3 Make sure that links work