Writing for the web - write for your audience

Government communications must be clear and concise. These guidelines on how to write English content for the web aim to ensure a standardised and consistent approach on South African government websites.

Follow these guidelines to make your web content easy to find, understand and use.

1. Purpose of the website

Most people come to a government website to complete a task. They expect to find information that will help them do that. Tasks can be:

• a transaction (submit a form or download a report)
• finding information (find out how to collect a benefit or find contact information).

People trying to complete a task online usually don’t read word by word. They scan quickly for words and links related to what they want to do.

Web content must therefore:

• give people who have no previous knowledge of the topic or process enough information to complete a task on their own
• give the appropriate details to specialists who have more knowledge of a topic or process
• present the most important information first, in a way that is tailored to the needs of the audience
• use a standardised approach on similar pages so that people can scan content quickly and easily

Prepare content in such a way that all potential users, irrespective of their education, background and sophistication can understand it.

Always keep in mind that “non-readers”, such as people with a low level of literacy, people whose first language is not English, and people with disabilities also use the Internet.

2. Structure information logically on pages

 Website users often scan pages to check if information is relevant before reading the detail. A logical structure for text and concise writing will assist the user in this.

Research has shown that when people scan web pages, they tend to start in the top left hand corner and scan to the right and down. As they move down the page, they scan less and less to the right.

Organise your content using an inverted pyramid structure to guide users to the information they need to complete their task. Start with the most important information and place less important information lower down on the page. Place supporting details such as links to relevant acts and publications toward the end of the text.

Structure the content components to make your page:

• more visible to search engines and easier to find by using headings that include keywords
• easier to view on mobile devices by using short sentences and paragraphs

General guidelines are:

• Structure headings and sub-headings logically.
• Keep content relevant to the respective headings.
• Use bulleted lists to list relevant information or to provide a lot of information in a concise manner.
• List items in order of relevance to the user. It must be logical to the user, not the department. Place important items at the top of lists.
• Use short sentences.
• Use short paragraphs with one idea per paragraph.
• Use page navigation items such as a list of contents with links to text lower down for long pages.

There is no minimum or maximum page length for a website. However, the quicker you get to the point, the greater the chance your target audience will see the information you want them to.

2.1 Page titles

Most people scan page titles and headings, looking for keywords that will confirm that they have found what they’re looking for.

When writing a page title, heading or subheading, make sure that it:

• gives a clear idea of what follows
• is short and contains no unnecessary words
• contains the most relevant terms at the beginning
• makes sense on its own and in search results

Example
Write: Regulations for e-tolls
Instead of: Regulations

• is followed by text and not by another heading, unless it introduces a table of contents on the same page
• uses sentence case
• has no punctuation at the end
• contains no abbreviation unless the audience knows the abbreviation or acronym better than it knows its long-form equivalent

2.1.1 Write descriptive page titles

The web page title typically appears as the linked first line in search results.

Your page title should accurately describe what is on the page. Search engines often display the page title without the context that the rest of the page provides.

Example
Write: Register premises as artificial insemination and embryo centre
Instead of: Register premises

Titles do not have to reflect an official publication title. Make them user-focused, clear and descriptive.

Use search statistics to find out what word the public uses for content you want to write about, such as jobs vs vacancies. Your programme’s official name may not be what users calls it. Use the most popular keywords in the page title, summary, introduction and subheadings.

Example
Good title example: Older persons grant or old age pension
Good summary example: An older persons grant is paid to people who are 60 years or older. This grant used to be called the old age pension.

Good title example: Finding a job
Good summary example: The information on these pages should help you to find a job, prepare you for the interview and for starting the job. We also provide links to government vacancies.

2.1.2 Make the page title unique

Most search engines identify relevant search results based on:

• page title
• headings
• subheadings

Unique page titles help search engines tell the difference between similar pages. They also help ensure that people do not have to look at many pages with the same name to find the information they need.

Check whether your page title is unique by using a search engine. Search for the title of the page followed by “site:” and the domain extension, for example, cabinet statement site:gcis.gov.za.

2.1.3 Title length

Your page title should ideally be 65 characters or less (including spaces).

You can use more characters if it is essential for making the title clear or unique, but do not do this routinely because:

• Google cuts off the title after 65 characters
• longer titles are harder to understand

2.1.4 Remove the date unless it is part of a series

Put the year in the title if the page is part of a series that has the same title, or if the date is important, as for an act of law.

Example:
Title: Government Communication and Information System Annual Report 2017/18
Title: Government Communication and Information System Annual Report 2016/17
Title: Government Communication and Information System Annual Report 2015/16

Example:
Title: Tax Administration Laws Amendment Act 13 of 2017

2.2 Headings and subheadings

Headings and subheadings give users a quick overview of the content on a page.

• Each page must have a main heading at the top. This should then be followed by subheadings of different sizes and weights to help users to understand the structure of the page at a glance.
• Use subheadings sparingly - users lose track if there are too many heading levels.
• Headings and subheadings should be:
• informative
• descriptive and clearly phrased
• in lower case, except for the capitalisation of the first letter (sentence case).
• The text should still make sense with the subheadings removed.

Do not use:

• gerunds
  Example
  Write: Apply for a licence
  Instead of: Applying for a licence

• questions
• technical terms unless you have already explained them
• acronyms
• ‘introduction’ as your first section – users do not want an introduction, just give the most important information

2.3 Use lists to help users scan

A short vertical list is easier for people to scan than a long paragraph. Aim for a maximum of 7 items in your list.

Take note of the following guidelines:

• Every item in the list should follow logically and grammatically from the lead sentence. 
  Example

Write: The purpose of the list is to:

• clarify
• make it easier to remember

Instead of: The purpose of the list is:

• to clarify
• it makes it easier to remember things
• Do not use semi-colons, commas or full stops at the end of each list item.
• Do not insert “and” after the second-last bullet sentence.
• Do not use an initial capital letter if the bullet point is not a full sentence and do not end with full stops.

Example
Research had indicated that we could create jobs in six priority areas:

• infrastructure development
• agriculture
• mining and beneficiation
• manufacturing
• the green economy
• tourism
• Capitalise the first letter of each bullet if it contains full sentences, and end each sentence with a full stop.

Example
Government established a jobs fund of R9 billion to finance new job-creation initiatives over the 3 years from 2011.

• According to the July 2017 Jobs Fund newsletter, it had a portfolio of 117 approved projects.
• These projects will potentially leverage an additional R8,6 billion from partners.
• A total of 110 projects have already created 100 055 new permanent jobs.
• Avoid having more than 1 sentence in a single list item or bullet point.
• Aim to make each list item a similar length.
• Avoid lists with more than 1 level.

Use numbered lists to show:

• ranking
• order
• priority
• step-by-step instructions.

Use numbered lists only if the order of the items is important.

3 Readability and plain language

Readability is the ease with which text can be understood by a reader. Readability tests look at words and sentences to measure how easy a document is to read. Plain language, using everyday words, simple sentences and direct language, is faster to read and sounds friendlier. Both are important to get your message across when writing for the web.

To make your content readable, consider your audience’s reading level. Not everyone reads at the same level or understands content in the same way. Even when content is presented clearly and simply, people who have low literacy levels or reading difficulties can find it hard to understand. In South Africa we also have to keep in mind that for most people, English is a second language.

Research shows that people with literacy challenges:

• spend a lot of time trying to understand words that contain more than two syllables
• read word by word and slowly move their eyes across each line of text
• skip over large amounts of information when it contains many multi-syllable words, uncommon terms and long sentences

When a user reaches a word or phrase that is unfamiliar or difficult it slows down their understanding. If they experience too much of this they lose confidence in the content and may give up.

Readability tools like Flesch-Kincaid help you check if English content is too wordy or complex. This tool is available as part of Microsoft Word and on the Internet. It generally reflects the years of education needed to understand the text. The aim is to write content for a reading level of grade 8 to help people to understand or complete their task.

3.1 Use plain language

Traditional government language is often unfriendly and difficult to understand, which is why it is important to use plain language to improve readability.

Writing in plain language does not mean over-simplifying or leaving out critical information. Using plain language makes critical information accessible and readable for everyone, even specialist audiences.

By writing plainly and simply, you:

• increase the chances that people will find, read and understand your information
• make your information more accessible to people with disabilities
• allow people who are reading your information on a small screen such as a smartphone to see essential information without scrolling too much
• make it easier to translate the information in any of the other official languages
• improve task completion and reduce enquiries

3.2 Readability and plain language at page level

Write for the Internet as a medium. Do not merely replicate printed products.

• Write clearly and concisely.
• Each page should be able to stand on its own, as users may view it without seeing other relevant pages.
• Each page must have a clear main point or topic.
• Use a professional tone – avoid clichés, jargon and humour.
• Limit the length of paragraphs to 3 sentences where possible. You can do this by:
• developing 1 main idea per paragraph
• presenting a series of more than 2 ideas or words as a bulleted list.

3.3 Readability and plain language at sentence level

Short sentences are generally easier to understand.

• Avoid complex and compound sentences. They generally contain too much information for people to understand when they are scanning.
  Example
  Write: Gauteng has the highest percentage of people aged 60 years and older. 
  Instead of: Of the elderly aged 60 years and older, the highest percentage reside in Gauteng.

• Try to keep sentences under 20 words. Do this by:
• breaking up long sentences into shorter ones
• limiting each sentence to one idea
• removing unnecessary words
  Example
  Write: You must register the birth of your child within 30 days after birth. Any one of the parents may register the birth.
  Instead of: In terms of the Births and Deaths Registration Act, any one of a newborn child's parents must within thirty days of the birth register the birth.

• Surround a long sentence with shorter ones as it helps people understand the long sentence.
• Limit the use of passive voice.
  Example
  Write: We will submit the students' information to the relevant universities.
  Instead of: The information received from students will be submitted to the relevant universities.

• Where possible, address the user personally, using words like “you” and “us”
  Examples
  Write: You must enrol your child in a school …
  Instead of: The child must be enrolled in a school...

  Write: If you pass the driving test  …
  Instead of: In the case of passing the driving test...

• Positive or negative form: Whenever possible, tell people what they may or must do instead of what they may not or must not do. Avoid negatives, double negatives and exceptions to exceptions.
  Example
  Positive: You must have a licence for any firearm that you own.
  Negative: You may not own a firearm without a licence.

3.4 Readability and plain language at word level

Using plain language means using short words that are generally understood by the public.

• Replace long words with short, simple and everyday words that most people understand and use. Simple words have 2 syllables or less. They’re easier to scan than long, complex words.
  
  Examples
  
  Write: ask
  Instead of: make a request
  
  Write: before
  Instead of: prior to
  
  Write: about
  Instead of: approximately
  
  Write: house
  Instead of: residence
  
  Write: try
  Instead of: endeavour

You can find more examples in the Editorial Style Guide, March 2013 [PDF] .

• Limit government jargon and technical terms. Legal and technical terms and “government-speak” confuse most people. If you must include jargon, explain it using simple, familiar words or give an example to help non-specialists understand.

Examples
Write: You have to file your income tax return (IT12) by 31 October.
Instead of: You have to file your IT12 return by 31 October.

• Avoid unnecessary words.

Example
Write: needs
Instead of: is in need of

Write: to
Instead of: in order to

• Write out words in full instead of using contractions.

Example
Write: was not
Instead of: wasn’t.

• Use terms consistently across the website when referring to the same thing.
• Use verbs instead of nouns formed from verbs.

Examples
Write: apply
Instead of: submit your application

Write: consider
Instead of: take into consideration

Write: modify
Instead of: make a modification

• Avoid noun strings (a series of 2 or more nouns used to name something).

Example
Write: The planning team will submit its final report on the development plan to Parliament.
Instead of: The development plan planning team will submit its final report to Parliament.

4 General guidelines

4.1 Captions

• Captions used for photos or images in the content must be short, but descriptive of the specific photo or image – not of the broader theme or event.
• Captions for images in a gallery should contain more information, unless you provide it in an introductory paragraph.

4.2 Acronyms and abbreviations

• When you use an acronym, write the full term out the first time it appears on a page, followed by the abbreviation in brackets. Thereafter, only use the acronym on that page.
  Example: Government Communication and Information System (GCIS)

• Do not use acronyms in menus and headings.
• Provide a glossary of acronyms used on the website as part of About the website.
• Avoid using e.g. and i.e. Use clearer alternatives instead.

Example
Write: for example, such as, or like
Instead of: e.g.

Write: that is, in other words
Instead of: i.e.

4.3 Hyperlinks

Hyperlinks allow you to link to more information on the same page, your department's website or other government websites.

• Use clear, known, plain, short and unambiguous terms in menus.
• Avoid acronyms as hyperlinks. The user may not know the acronym.
• Keep link text as close as possible to the name or the heading of the page you link to.
• When you use links within text, hyperlink the words describing the website, information or document you link to. Do not use “click here” or the URL of the website.

Example
Write: The Department of Basic Education (DBE) is responsible for Outcome 1 (quality basic education) of government’s Medium Term Strategic Framework (MTSF) 2014-2019.
Instead of: The Department of Basic Education (DBE) is responsible for Outcome 1 (quality basic education) of government’s Medium Term Strategic Framework (MTSF) 2014-2019. For the document click here.
Or : The Department of Basic Education (DBE) is responsible for Outcome 1 (quality basic education) of government’s Medium Term Strategic Framework (MTSF) 2014-2019. Find the document at https://www.gov.za/documents/medium-term-strategic-framework-2014-2019.

• Do not overcrowd text with links.
• Hyperlink all email addresses. 

4.4 Capital letters

Capitalise only when necessary:

• Capitalise the first letter only (sentence case) for headings, sub-headings, and menu entries.

Example
Write: Support for learners with intellectual disabilities
Instead of: Support For Learners With Intellectual Disabilities.

Example
Write: Second Chance Matric Support Programme

• Capitalise the main words of:
• titles of official publications such as reports, frameworks, strategies and plans
  Example: White Paper on International Migration for South Africa
• institution names
  Example: Culture, Arts, Tourism, Hospitality and Sports Sector Education and Training Authority
• programme names
  Example: National School Nutrition Programme
• titles of legislation (acts, bills and regulations)
  Example: Financial Intelligence Centre Amendment Act 1 of 2017
• Use all capitals only for a name or title where that is the official name used and known by the public, such as CSIR.

4.5 Underlining, bold and italics

• Never underline text or headings, as it could be mistaken for a hyperlink. Use bold.
• Use bold for emphasis, but use it sparingly: the more you use it, the less effective it is.
• Do not use italics, as it is difficult for people with dyslexia and other reading disorders to read.

4.6 Punctuation

Best practices for easier on-screen reading include:

• Never use full stops after headings.
• Limit punctuation.
• Avoid using semi-colons.
• Avoid dashes. Rather use commas.

4.7 Symbols

Some symbols make web content more difficult to read while others improve readability. Research whether they are understood by a wide audience before using them.

4.7.1 Ampersand

Write out the word “and” instead of using an ampersand (&) where it is not part of a registered name or an abbreviation.

Example
Write: Department of Science and Technology
Instead of: Department of Science & Technology

Write:

• R&D (research and development)
• O&M (operating and maintenance)

4.7.2 Percent

Use the symbol (%) with no space between the numeral and the symbol.

Example
Write: 20%
Instead of: 20 percent or 20 per cent

4.7.3 Currency

Use the symbol for currency with no space between the R and the numeral.

Example
Write: R100 per month

4.8 Numbers

Research has shown that when people scan on the web, they often stop at numerals. People are interested in facts as represented by numerals.

• Write numbers as numerals (0, 1, 2, 3, etc.), except in:
  • proper names or titles
    Example: Fifth International Climate Change Adaptation Conference
  • figurative expressions
    Example: one day, things will be better.
  • Keep Roman numerals when used in proper names
    Example: King II Report).
  • Place a non-breaking space (Ctrl+Shift+Spacebar) between all numeral and word combinations (R5 million, 20 years) and for the decimal indicator (10 000) to keep them in the same line.
  • Use the ordinal indicator in the same text size (not in superscript) for numbers
    Example: 10th, 50th, 150^th.
  • Use “to” instead of an en dash in number ranges
    Example: R4 000 to R10 000, 4 to 10 years.

4.8.1 Ages

Write:

• Adults aged 30 or more
• People 30 to 65 years old
• A 10-year-old child
  • Always use the format dd-mm-yyyy
  • Write dates without an ordinal indicator (“st,” “nd,” “rd,” “th”)
    Example:
    Write: 31 July 2018, or just 31 July if the year is already clear
    Instead of: July 31st, 2018, 31st July 2018 or July 31^st or 31st July.
  • Use non-breaking spaces between the month, the day and the year
  • Use the numeric date format (31/07/2018) only when space is limited such as  in a table)
  • Abbreviate month names when space is limited (for example, Jan., Feb., Mar.),otherwise write them out.

4.8.2 Dates

When you use date ranges:

• use “to” instead of an en dash in date ranges. For example:
  • Monday to Friday
  • 1 March to 28 February
  • financial year 2015 to 2016

4.8.3 Time

Use either:

• 16:30 or 4:30 pm
• 09:00 to 17:00 or 9 am to 5 pm

Stick to one style throughout the page.

Do not write: 16:30 pm. 16:30 already indicates that it is pm.

4.8.4 Phone numbers

Use phone numbers without brackets for the area code. Use spaces between groups of numbers for easier reading. For example:

• Report fraud at 0800 601 011.
• 012 473 0000 or +27 12 473 000.

4.9 UK English

In South Africa, the UK version of English is used, and not the American version.

Examples
Write: organisation
Instead of:  organization

Write: honour
Instead of:  honor

Write: programme
Instead of:  program, except for a computer program

Write: catalogue
Instead of: catalog

Write: centre
Instead of: center

Write: realise
Instead of:  realize

Write: specialise
Instead of:  specialize

4.10 Gender-specific language

Write content to be gender-neutral.

• Avoid using she/he or his/her.
• Use “you” instead of “the applicant”.

Example
Write: You must go to the SASSA office to apply.
Instead of: The applicant must go to the SASSA office...

• Rephrase to remove pronouns.

Example
Write: If the spokesperson is unavailable, please send an e-mail
Instead of: If the spokesperson is unavailable, please e-mail her/him.

• Use gender-neutral equivalents for gender-specific words.

Examples
Write: chairperson
Instead of: chairman

Write: work hours or person hours
Instead of: man-hours

Write: spokesperson
Instead of: spokesman.

4.11 Using print publications on the website

Websites differ from print. When you convert print material to html it should be adapted to the format and style of the web. Ways to do this include:

• Review the accuracy and relevance of information for the website audience.
• Reposition documents for online reading by editing and rewriting it.
• Restructure information.
• Add hyperlinks to relevant information.
• Prepare an index or a summary and include links to the relevant parts of the document.
• Add a link to the printable version of the document (PDF).

For more information on government writing, consult the government Editorial Style Guide [PDF].