Content writing

Content writing is the practice of writing text content for a user interface that helps users to achieve their desired goals and outcomes. This can range from page content and headers to buttons, labels, and more. Written content can help users to understand the purpose of UI functionality, improve usability, and reduce the chance of errors and feelings of frustration. Written content is especially important to users of assistive technology, such as screen reader users. Without visual cues, screen reader users may rely more heavily on written content to achieve their goals and outcomes.

Best practices

User-centric

Good content writing is user-centric, always prioritizing the needs and goals of the user. All written content should help the user to achieve their desired goals or outcomes. Any information that does not contribute to achieving the current goal could distract from key information and may be best placed elsewhere.

Simplicity

Good content writing is simple and concise. A Neilson Norman Group study found that 79% of test users always scanned a new web page. Keeping text concise, structuring text so that it was scannable, and using objective and neutral language drastically improved usability. To keep text simple and concise:

• Write content at a grade 8 reading level on the Flesch-Kincaid scale (you can use Microsoft Word to easily measure reading level)

• Use short words and sentences

• Use plain language and avoid technical jargon

• Use headings and sub-headings to break up content and make it easier to scan

• Avoid the use of double negatives

• Use numerals (2) rather than writing numbers (two)

• Avoid the use of acronyms

• Use bullet points when appropriate to make content easier to scan

• Write in sentence case, with the exception of proper nouns

For more tips on how to write in plain language, see the Plain Language Writing Guide.

Sentence case exceptions

While we recommend using sentence case most of the time, the Canada.ca Content Style Guide provides a list of exceptions that use title case. We suggest following the same guidelines for internal applications as well. These are listed below with examples.

Capitalize the main words of the following items in text, links and applications:

• Titles of official publications (such as reports, frameworks, strategies and plans)
  For example, Oceans Protection Plan

• Institution names
  For example, Transport Canada
  For a list of Government of Canada Institutions, please see Institutions list for Canada.ca - Canada.ca

• Program names
  For example, Small Vessel Compliance Program
  For a list of Transport Canada programs, please see Programs (canada.ca)

• Titles of policy instruments
  For example, Safety and Security Program Policy Framework

• Titles of legislation (in other words, acts and regulations)
  For example, Canada Shipping Act, 2001

• Government of Canada

It is recommended to use lowercase for the short form of proper names. For example, when The Nairobi International Convention on the Removal of Wrecks, 2007 is shortened to “wreck” or “wreck certificate” these would both use lowercase.

Consistency

Good content writing is consistent across the application and service. This helps to avoid confusion and creates a holistic and uniform experience for users. Ensure that you are using the same language in all applications, systems, and services your users may interact with. This may include similar services or applications not owned by your team. Keep the language consistent with the language your users use to match their mental model.

Inclusive

The Guidelines for Inclusive Writing are designed to help the federal public service and any other organization produce writing that is free of discrimination based on sex, gender, sexual orientation, race, ethnicity, disability or any other identity factor. Inclusive writing is a practice you can use in your daily writing, but most importantly, needs to be used when writing any public-facing content, such as web pages and software applications. It is also a good idea to try to incorporate inclusive writing into user research materials such as interview guides and usability testing scripts.

For more information, and for tips on inclusive writing in French, visit the Inclusive writing - Guidelines and resources page.

Common types of content writing

Buttons

Text for buttons should be kept short yet descriptive. Use common action verbs to help users to understand what action they are initiating when they interact with the button.

Buttons in modals are an exception to using action verbs for labelling. As seen in the Guidelines on Modals, buttons should be labelled ‘Confirm’ to proceed, or ‘Cancel’ to not proceed with action described in the modal. The content within the modal should clearly explain the action or decision the user is being asked to make and worded in a way that is clear what will occur when the user selects ‘Confirm’ or ‘Cancel’.

Example

In Figures 1 and 2, the user is being asked if they would like to proceed with an irreversible action, deleting a service request:

Figure 1 shows poor button labeling. The button label at the conclusion of the form, “Done”, is ambiguous and does not make it clear what action will occur when selected. “Done” could be interpreted as being done this page of the form and being ready to move on to the next page. Alternatively “Done” could be interpreted as being done filling out the entire form and being prepared to submit the form. The ambiguity of the button label could result in irreversible errors and frustration.

Open

Figure 1 - Poor button labelling at the end of a form

In Figure 2, the button has been labelled according to content writing best practices. The “Submit” button explicitly states what action will be performed if selected, leaving little room for ambiguity and error.

Open

Figure 2 - Descriptive button labelling at the end of a form

Link to templates - TBD

Learn more about buttons.

Titles and headers

Page titles and headers help to break up page content, making it easier to scan and locate the content relevant to the user’s goal. Titles and headers should be concise, make use of keywords, and communicate the goal or outcome they are relevant to.

Example

Figures 3 and 4 portray an informational web page designed to help users understand how to obtain a boating license:

Figure 3 shows poor use of titles and headers. The page title is unnecessarily wordy, making it challenging to scan for keywords. Plain language has not been used in the title, some language could have been simplified and acronyms could have been spelled out. Additionally, the content of the page is formatted in two rather dense paragraphs with no headers, making it challenging to scan for key information.

Figure 4 demonstrates better use of page titles and headers. The page title is concise and written in plain language. Page content has been split up into smaller paragraphs made up of 2-4 sentences. Each paragraph focuses on one theme or message and has a heading that succinctly reflects that theme or message. These considerations make the page easier to scan for keywords and key content.

Link to templates - TBD

Alerts and messages

Alerts and messages help to inform users of important information and to guide or prompt them if a follow-up action is required. They should focus on providing the user with meaningful, and if necessary, actionable information. Keep alerts and messages concise and focused on why they are being shown. In the case of error messages, do not place the blame on the user:

Examples

Figures 5 and 6 show error messages informing the user that an action they requested failed due to an unexpected error.

Figure 5 demonstrates a poorly written error message. The error message reads “Oops! Something went wrong, please try again.” This message does not help the user to understand why it is being shown. Furthermore, there is no explanation as to whether the error that occurred can be resolved by the user, and if so, how they should go about doing this.

In Figure 6, the error message is written using best practices. “Application #123456 could not be assigned due to an unexpected error, try again.” The message is concise and focused, it focuses on why the message is being shown and what can be done to correct the error that occurred.

Link to templates - TBD

Learn more about alerts and messages.

Labels

Labels for UI components like form fields, radio buttons, or checkboxes help to communicate to the user the purpose of the component and the value they are expected to input. Labels should be concise and focus on communicating what the user needs to input. Further instruction should be reserved for inline help text, such as instructing a user on how to format their date of birth.

Examples

Figures 7 and 8 show date of birth fields with different labels.

Figure 7 demonstrates an unclear form field label. The label is a rather wordy and an uncommon way of requesting the user’s date of birth.

Figure 8 is much more concise and a more commonly used term for requesting a user input their date of birth. This makes it easier for the user to scan and recognize what is being asked of them.

Link to templates - TBD

Resources

Government of Canada resources 

Canada.ca Content Style Guide - Plain Language

External resources 

A Quick Guide to Writing Better Button Labels

16 Rules of Effective UX Writing

Labels UX Writing: A Step-by-step Guide