Web writing basics guide

Be clear on the audience and purpose of your content before you start writing.

• Define your audience up front, and list the key tasks they should be able to complete with your content.
• Use words the audience is familiar with.
• Don’t write content without knowing who it’s intended for.

• Organise content based on user needs, not organisational structure or internal ownership.
• Use plain English. Aim for Grade 9 level (or lower) readability.
• Use short sentences. Avoid multiple clauses.
• Use common words (e.g. ‘fix’ instead of ‘rectify’, ‘aware’ instead of ‘cognisant’).
• Put the most important information at the top of the page.
• Don’t state the obvious.
• Use inclusive language.
• Use active voice (e.g. ‘We consulted with the community.’ Not, ‘The community was consulted.’).
• Try to use verb-based sentences rather than nominalisations (e.g. ‘Apply by 1 June.’ Not, ‘Applications must be submitted by 1 June.’).
• Use personal pronouns (‘we’ for UQ and its organisational units, ‘you’ for the audience).
• Don’t use jargon (including acronyms and initialisms), puns, cliches, academic-speak, uncommon words, colloquialisms or idioms. 
  • If you must use an acronym or noun string to name something, use a simple term rather than an acronym for subsequent references (e.g. ‘The Temporal Perception of Dogs Study’… The study).
• Remove redundancies, such as:
  • redundant synonyms (true and correct)
  • redundant modifiers (separate out)
  • adjectives and adverbs (most can go)
  • transition words and phrases (therefore, at this point in time, hence)
  • redundant categories (blue in colour).

• Use sentence case.
• Use single spaces.
• Use sans serif fonts. The block-like appearance is more readable.
• Use % (not per cent).
• Use numerals rather than words for numbers. (Unless using ‘one’ or ‘zero’ in a non-literal way, or when starting a sentence. ‘One way to get involved is to…’).
• Use lists when possible – these help to speed up reading. Avoid big blocks of uninterrupted text.
• Don’t use centred or justified text. Left aligned only.
• Don’t underline text (unless default link text styling).
• Don’t use full caps.
• Avoid italics.

Headings and subheadings make it easier for users to quickly find the information they need.

• Headings should be short and simple but also meaningful.
• Use parallel language across headings.
• Use one H1 heading per page.
• Use H2 for the main subheadings on a page.
• Use subsequent subheadings (H3, H4, etc.) in descending order (e.g. H3 is used to organise content under H2).
• Don't skip a heading level (e.g. jump from H2 to H4).
• Don’t use headings for style reasons (e.g. to make text bigger).
• Don’t use bold text or full capitals instead of a heading.

Images and icons should only be used when they add meaning and make your content easier to understand.

• Use alt text to explain what the image contains. (e.g. Vice Chancellor Deborah Terry presenting an award to Grade 10 students from Toowoomba High.).
• Where possible, avoid infographics or process flows. If you must include an infographic, include text alternatives, such as a numbered list to show process order. Include alt text on the infographic describing where the text alternative is (e.g. 'A text description of the payment process is below’).
• Don’t use images as the only way to convey information.
• Don’t use images of text.

Links and buttons should be accurate, descriptive and specific.

• Write descriptive link text that helps users understand where the link will take them (no ‘click here’ or ‘read more’).
• Buttons should always contain an action. Make sure the user knows what will happen when they click the button (e.g. ‘log in’, ‘apply’).
• Links should open in the same window.
• If linking to a document, include the document type and file size in brackets (e.g. Study at UQ: Program page content sources (PDF, 5.3 MB)).
  • New Drupal will do this automatically when you link to a document. When working in Drupal 7 you will need to tick the ‘Display file type and size in link’ box.
• Buttons should be used sparingly. Don’t use a button if a regular link will do.

Tables make it easy for users to compare related data across multiple columns or rows.

• Only use tables for tabular data. Don’t use tables for layout reasons (e.g. to make text columns).
• Tables should be simple.
• Use the caption element to give the table an informative title.
• Use headers that apply to the whole column or row.
• Don’t nest tables within tables.
• Don’t merge cells.

Publish content on web pages rather than documents as much as possible. If you do publish documents (e.g. PDFs, Excel spreadsheets), you must:

• use headings and follow hierarchy rules
• set the reading order for tables (column A, then column B, then break-out box, etc.)
• include a table of contents and jump links for longer documents
• use metadata to provide information on the contents of the document. To add metadata to a PDF:
  • open ‘document properties’
  • add an appropriate title (use the H1), author (The University of Queensland) and subject (brief description of the document)
  • click ‘ok’ and save the document.

• Write for the web
• Written style guide
• Tone of voice guidelines
• Web publishing
• Inclusive language

• Australian Government Style Manual
• How users read on the web
• The problem with PDFs

• Use Hemingway and Grammarly to improve your writing and spot errors.
• Use Wave to check how accessible your web pages are.
• Use Copybank for easy copy snippets about UQ.
• Check Macquarie Dictionary for correct spelling.