Skip to content

Latest commit

 

History

History
77 lines (49 loc) · 3.13 KB

style-guide.md

File metadata and controls

77 lines (49 loc) · 3.13 KB

Style guide

General

In general:

  • use as few words as you can to accurately say what you're saying
  • prefer simple words over complicated ones
  • avoid business-speak and overused idioms
  • tone should avoid be overly formal, but not to the point of becoming colloquial
  • break your work up into short paragraphs, and consider using subtitles and images to break up the text

Punctuation

Do this:

  • don't use hyphens to delineate bits of sentences -- like this. Instead, use commas, a colon, or parentheses
  • capitalise proper nouns, words at the beginning of sentences, and (if appropriate) abbreviations and nothing else
  • don't capitalise every word in a title
  • avoid semicolons unless they are definitely right
  • numbers should use commas: £1,000 not £1000
  • dont get apostrophe's wrong or dxws' reputation will forever be ruined

Tone

Do this:

  • always remember our values: in particular, making sure we're helpful and positive
  • don't say things like "we're experts in WordPress". Instead, say things show that that sentiment is true (for example we've hosted some large sites for important folk)
  • make factual statements about the customer rather than our understanding of them:
    • "You've said that" rather than "We assume that" or "An assumption has been stated that"
    • "Your staff have experience administering WordPress" rather than "We understand that your staff..."

Strongly discouraged words and phrases

It's fine to use these if they really are the best words to use, but be mindful that they usually aren't. Some of these are cribbed from the

Tired idioms

Do not use:

  • in terms of (very rarely actually used to describe one thing in terms of another and is often a verbal tick which can usually just be omitted)
  • look to
  • with regards to
  • separate out (the 'out' is redundant)
  • we will aim to... (are we doing it or not?)

A-Z

In addition to the list below, we also follow the GOV.UK style guide. This gives lots of information about words and phrases specific to the public sector.

Digital Marketplace: the government procurement website should be capitalised as it is a proper noun to distinguish it from other digital marketplaces (like eBay).

dxw: in client-facing/public-facing documents, dxw should be lowercase.

G-Cloud: formatted thusly with hyphen and capital letters. Never 'G-cloud' or 'g-cloud' or 'G Cloud' or 'GCloud'.

GovPress: not 'Govpress' or 'Gov Press'

multisite: if referring to the feature directly, "Multisite" should be capitalised. If referring to an multisite WordPress setup, "multisite". Never "multi site" or "multi-site".

open source: always lower case.

plugin: not 'plug in' or 'plug-in'.

Rails: for the Ruby framework, always upcase. Lower case is fine for the things trains run on.

WordPress: not 'Word Press', 'Wordpress' or 'WP'.

Words to avoid

GOV.UK have a list of words to avoid, which we also follow. In addition:

  • platform (unless it actually is one)
  • portal (unless to another dimension)