Writing Web Content

Writing content for the web is different than writing for other media. Website users do not read web content, they skim/scan it looking for the information that is important to them, or to complete a task. When writing web content, keep these best practices in mind.

Focus on the user

Before you start writing content, identify who your target audience is and what their needs and motivations are for visiting your page/site.

Create user stories or personas for reliable and realistic representations of your key audience segments for reference when designing services and content outlines.

If you don’t think about who your users are and the tasks they are trying to complete, you will be creating content for yourself.

• Who are our main users?
• What are their motivations for coming to the website?
  • What do they want / what are their needs / what are they looking for?
  • What tasks are they trying to complete?
• What benefits will users get from what you’re creating?
• What are our customer service goals?
• What are the calls-to-action?

Content outline

After identifying the needs of your users, create a user-focused content outline:

• Think about how the user will move through pages/sites to complete a task, and make that as intuitive as possible
• Bring tasks and important information to the forefront
• Make online services prominent
• Keep to a topic/service-based structure and not an organizational structure
• How will the user interact on a mobile device? On small screens, important content must be prioritized to give the user the content that they need.
• Think about the topic/service area landing pages, how different pages link to sub-pages, and how all those sub-pages interact with one another.

Writing Style Guide

The City of Winnipeg Writing Style Guide is a resource to use when drafting written materials. The guide defines and explains the writing guidelines for all internal and public-facing materials to ensure consistency across the organization.

The guide may be referenced for City standards in spelling and grammar, writing style, naming conventions, formatting style, translation requirements, as well as brand standards, accessibility standards, and digital and web standards.

Tone & voice

The following are additional tips to keep in mind:

• Always use the active voice (i.e. use verbs, action words)
• Don’t refer to yourself in the third person – avoid saying things like “The City of Winnipeg is…”; instead, use "we," "our," etc.
• Avoid writing formally – while you need to maintain a professional voice, it doesn’t mean it needs to be formal

Write accessible, user focused content

When writing for the web:

• Consider user needs and keep customer service goals in mind
• Put important information first before providing additional details. Does the first sentence help users to decide if the page is relevant?
• Use the active voice
• Use plain language and familiar terms. This helps users to understand the content on the first read-through.
  • Use simple words and phrases - Plain Language Action and Information Network
• Write to a maximum grade 8 level. Verify readability using the Hemingway App before content is approved and translated.
• Chunk related content into short, scannable groups
• Use useful headings and subheadings, and make them meaningful
  • Add useful headings - Plain Language Action and Information Network
• Keep paragraphs short and have one topic per paragraph
• The opening sentence should be the topic sentence
• Be concise
  • Choose a shorter word over a longer one
  • Use short, simple sentence structure
  • Always try to eliminate any unnecessary words
• Use bulleted lists
• Avoid using all uppercase characters
• Use short, meaningful links. Do not use "click here"; use a descriptive call to action instead.
• Avoid using FAQs; they often duplicate content. Instead, organize your content in a logical way to help your user find a clear path to the information they are looking for.
  • Avoiding FAQs, with one exception - Canada.ca blog

Writing resources

• Writing for web accessibility - W3C Web Accessibility Initiative
• plainlanguage.gov - Plain Language Action and Information Network
• Hemingway App

Descriptive link text

Link text should be meaningful enough to make sense when read out of context, succinct, and clearly identify the target of the link.

Keep in mind that screen reader users may have their software read the links on a page without the rest of the text.

Test your links by reading just the links in your content out loud. This will help you verify if they make sense out of context.

• Do not use “link”, "click here" or "read more" as link text.
• Do not use a URL address as a link, as they are not human readable.
  E.g. https://winnipeg.ca/PublicWorks/snow/default.stm
• A vanity URL can be used as a link to create a customized, meaningful and memorable link name. E.g. winnipeg.ca/snow

Examples

Open links in the same tab or window

To meet accessibility requirements, most links should not open in a new window (target="_blank"). W3C indicates the following exceptions:

1. Opening a page containing context-sensitive information, such as help instructions, or an alternate means of completing a form, such as a calendar-based date picker, will significantly disrupt a multi-step workflow, such as filling in and submitting a form, if the page is opened in the same window or tab.
2. The user is logged into a secured area of a site, and following a link to a page outside of the secured area would terminate the user's logon. In this case opening external links in an external window allows the user to access such references while keeping their login active in the original window.

Resources for writing meaningful links

• Writing Hyperlinks: Salient, Descriptive, Start with Keyword - Nielsen Norman Group
• A Link is a Promise - Nielsen Norman Group

Images & charts

If you are providing an image, chart, or other visual element to be added to the site, ensure they meet web and accessibility standards.

• Is the image informative or decorative? Informative images add additional information not included in the text on the page.
  • If the image is informative, ensure that it meets accessibility standards - the image should not include text.
  • If the image must include text (e.g. logo, chart) this text will also need to be included in the accompanying content on the page.
  • Ensure that there is sufficient contrast in the image/chart/graph (you can use an online contrast checker for this)
  • If the image is decorative, consider whether the image is actually needed. Decorative images provide no added value to the user.
• Tabular data should be built as text and HTML code to ensure accessibility, not provided as an image.
• Dynamic charts can be built using web tools, unless they are too complex to reproduce.
  • If a chart must be included as an image, ensure alt text makes the chart contents clear.
  • If the information provided in the chart is too complex to explain in alt text, include the information as text content, and/or include the tabular data the chart uses as an alternate format.
• Maximum width of images is 808px w.
• Image quality and resolution must be high enough for use on the website.

Alt text

Users who are unable to see images presented in a website or document depend on alternate text (alt text) to communicate the content of an image.

When screen readers encounter an image with alt text, they typically announce the image then read the alt text. As such, avoid starting your alt text with “image of…” or “photo of…”.

• Alt tags should describe the image, keeping in mind the context of the page.
• Alt text should be kept short and simple.
• A null alt tag is appropriate for:
  • decorative images that do not provide additional information, context or meaning,
  • images where alt text would be redundant in cases where the information is located elsewhere in the content. For example, if the description of the image is already part of the body text or image caption.
• Longer descriptions (more than about 125 characters) should be included in the body text of your document, rather than as alt text.

Resources for writing alt text

• Everything you need to know to write effective alt text - Microsoft
• An alt Decision Tree - W3C Web Accessibility Initiative
• Text alternatives – a decision tree – 4 Syllables
• Long descriptions for images – part 1 – 4 Syllables
  • The role of long descriptions for images is explained including why you need them and how to implement them.
• Long descriptions for images – part 2 – 4 Syllables
  • A look at long descriptions/text alternatives for complex or detailed images: charts and graphs, maps and plans, infographics, diagrams and technical drawings.
• Writing text alternatives for maps – 4 Syllables
  • How to write text alternatives for simple and complex images of maps.

Documents

The City of Winnipeg is moving towards having an HTML-first approach to document creation, instead of designing print-first PDF documents. This will ensure documents and reports are accessible, mobile-friendly, can be tracked more easily for web stats, and are easier to keep up-to-date for living documents and guides.

Documents should be provided as Word documents with proper heading levels that can easily be made into an HTML document in our Drupal Content Management System.

All guidelines in this document for web content, including content writing, heading structure, images, charts, alt tags and French translation apply to all formats of documents.

Download the City of Winnipeg's accessible Microsoft Word template (DOCX, 114KB)

PDF documents

If a PDF document must be posted on the City’s website, it needs to be accessible.

In order for a PDF document to be accessible, it must be a “tagged” PDF, with an underlying tagged structure that enable people who use screen readers and other assistive technologies to read and navigate a document.
The easiest way to make an accessible PDF is to ensure the original document is accessible.

Create accessible documents in Microsoft Office

Using the Microsoft Office Accessibility Checker before saving a document as a PDF will inspect the document and provide recommended actions to improve the accessibility.

• Improve accessibility with the Accessibility Checker – Microsoft
• Make your Word documents accessible to people with disabilities - Microsoft

Once the original document’s accessibility issues have been addressed, the document information should be reviewed.

PDF documents should always include a title, and the easiest way to do this is to add the title in the original document. Go to File > Info. Under “Properties” (in Word it’s in the right column of this tab), add a document title.

When you are in the info section, review the “Related people” section, as this also will be saved within the PDF as well, and will be publicly visible. To remove a name from the document info, right-click on the name and click “Remove person”.

Once the file has been made accessible, and the document properties have been reviewed, save the file one more time to retain a final, accessible version of the original. The next step is to save it as a PDF with accessibility tags - but there is a right and wrong way to do this.

Create accessible documents in InDesign

When using InDesign to create content that will be saved as a PDF, make sure to use accessibility features when creating the InDesign document. PDF tags, alt tags and the content order you assign in InDesign will stay with the document as you export it.

• How to use InDesign and Acrobat to create content that is accessible - Adobe
• Creating accessible PDF documents with Adobe InDesign CS6 - Adobe

French content

Public-facing materials, including brochures, pamphlets, advertisements, website content, social media, etc. must be translated into French under the following circumstances:

• If the initiative is related specifically to the Riel District (St. Boniface, St. Vital, and St. Norbert - Seine River wards, as well as portions of Transcona)
• If the initiative has city-wide implications
• For guidance on providing services in both official languages, contact French Language Services at City-FR@winnipeg.ca

Promotional information

Include the following additional information about the page/site for use in service listings, promotional feature cards, etc.

• Title
• Short description of the service/information/event, or call to action
• Keywords
• Feature card image size is 808px w x 454px h