-
Notifications
You must be signed in to change notification settings - Fork 26
Style guide
Mike Hitchins edited this page Dec 13, 2023
·
32 revisions
The following principles are designed to provide guidance on writing content for the web (although the standards are equally applicable to document writing). This is to ensure clarity and consistency in our messages both internally and externally for GP Connect.
Titles should be initial capped and then lowercase (unless a word is a name or acronym):
- Getting started
- Implement a capability pack
- Integrate with Spine
- Development guidance
- GP Connect developer ecosystem
Some words are always capitalised (because they are names):
- GP Connect
- Spine Security Proxy
- Spine
- Personal Demographics Service
- Organisation Data Service
- Spine Directory Service
Names of capability packs:
- Foundations
- Access Record HTML
- Access Record Structured
- Appointment Management
- Task Management
Acronyms are usually capitalised:
- GP
- IT
- FHIR
- DSTU2
- NHS
- API
but not always:
- dm+d
Also:
- EMIS Health (company)
- EMIS Web (product)
- TPP (company)
- SystmOne (product)
- Vision (company)
- Vision (product)
- Microtest Health (company)
- Open Evolution (product)
Other points:
- NHS number (lower case 'n', as in this usage.)
- GP practice - with a lower case p.
- The word ‘patient’ is lower case in the middle of a sentence.
- Endpoint
- Precondition
- Postcondition
- GitHub/GitFlow
- From the FHIR site: ‘When referencing the FHIR® standard in a web site, document, presentation, or otherwise, please in a place of prominence refer to it as the "HL7® FHIR® standard". In subsequent uses, please refer to it as the "FHIR® standard" or "FHIR®", using the ® symbol as often as is practical, at least once on each page of printed matter, generally in connection with the first or dominant usage.’
- a number of - use 'several', 'a few' or if possible state the specific number. Alternatively, use a collective noun so that 'FHIR has a number of resources' becomes 'FHIR has a collection of resources'.
- in order to - use 'to'.
- Don't use 'e.g.' or 'i.e'. Use '- for example,' and '- that is,'. The exception, though, is in tables where space is at a premium.
We refer to the style guides listed below:
- GOV.UK style guide
- GOV.UK writing guidance
- NHS Digital style guidelines
- NHS Digital Content style guide
Here are some aspects of style (taken from these style guides) that are particularly applicable to our work on the Development Portal (GitHub):
Abbreviations and acronyms:
- The first time you use an abbreviation or acronym on a page explain it in full, followed by the acronym in parentheses. This includes government departments or schemes. Then refer to it by initials, and use acronym Markdown so the full explanation is available as hover text.
- Acronyms which do not need to be explained are: UK, DVLA, US, EU, VAT, MP, HTML, HTTP, BST, UTC, URL, URI, API, ID, JSON, HTML, XML, FHIR, GP, NHS
- If you think an acronym is well known, please provide evidence that 80% of the UK population will understand and commonly use it. Evidence can be from search analytics or testing of a representative sample.
- Don’t use full stops in abbreviations: BBC, not B.B.C.
- Don’t use an acronym if you’re not going to use it again later in the text.
Active voice:
- Use the active rather than passive voice. This will help us write concise, clear content. For example, 'An automated provider test harness is publicly available' rather than 'An automated provider test harness has been made publicly available'.
Addressing the user:
- Address the user as ‘you’ where possible.
Ampersand:
- Use ‘and’ rather than &, unless it’s a department’s logo image or a company’s name as it appears on the Companies House register.
Bold:
- Don’t use bold. Use headings or bullets instead if you want to emphasise particular words or sections.
Bullet points and steps:
- You can use bullet points to make text easier to read. Make sure that:
- you always use a lead-in line
- the bullets make sense running on from the lead-in line
- you use lower case at the start of the bullet
- you don’t use more than one sentence per bullet point - use commas or dashes to expand on an item
- you don’t put ‘or’ or ‘and’ after the bullets
- if you add links they appear within the text and not as the whole bullet
- you don’t put a semicolon at the end of a bullet
- there is no full stop after the last bullet point
Steps:
- Use numbered steps instead of bullet points to guide a user through a process. You don’t need a lead-in line and you can use links and downloads (with appropriate Markdown) in steps. Steps end in a full stop because each should be a complete sentence.
Capitalisation:
-
DON’T USE BLOCK CAPITALS FOR LARGE AMOUNTS OF TEXT AS IT’S QUITE HARD TO READ.
-
Always use lower case, even in page titles (apart from the first letter). The exceptions to this are proper nouns, and:
- departments (specific government departments - see below)
- the Civil Service, with lower case for ‘the’
- job titles, ministers’ role titles: Minister for Housing, Home Secretary
- titles like Mr, Mrs, Dr, the Duke of Cambridge (the duke at second mention)
- buildings
- place names
- brand names
- faculties, departments, institutes and schools
- names of groups, directorates and organisations: Knowledge and Innovation Group
- titles of specific acts or bills: Housing Reform Bill (but use ‘the act’ or ‘the bill’ after the first time you use the full act or bill title)
- names of specific, named government schemes known to people outside government: Right to Buy, Queen’s Awards for Enterprise
- specific select committees: Public Administration Select Committee
- header cells in tables: Annual profits
- titles of books (and within single quotes), for example, ‘The Study Skills Handbook’
-
Don’t capitalise:
- government
- minister, never Minister, unless part of a specific job title, like Minister for the Cabinet Office
- department or ministry - never Department or Ministry, unless referring to a specific one: Ministry of Justice, for example
- white paper, green paper, command paper, House of Commons paper
- budget, autumn statement, spring statement, unless referring to and using the full name of a specific statement - for example, “2016 Budget”
- sections or schedules within specific named acts, regulations or orders
- director general (no hyphen), deputy director, director, unless in a specific job title
- group and directorate, unless referring to a specific group or directorate: the Commercial Directorate, for example
- departmental board, executive board, the board
- policy themes like sustainable communities, promoting economic growth, local enterprise zones
Data:
- Treat as a singular noun: The data is stored on a secure server.
FAQs (frequently asked questions)
-
FAQs are strongly discouraged on GOV.UK. If you write content by starting with user needs, you won’t need to use FAQs.
-
FAQs are discouraged because they:
- duplicate other content on the site
- can’t be front-loaded (putting the most important words people will search for), which makes usability difficult
- are usually not frequently asked questions by the public, but important information dumped by the content editor
- mean that content is not where people expect to find it; it needs to be in context
- can add to search results with duplicate, competing text
Italics:
- Don’t use italics. Use single quotation marks if referring to a document, scheme or initiative.
Sub-headings
- Make sure your sub-headings are front-loaded with search terms and make them active.
Don’t use:
- gerunds, for example ‘Apply for a licence’ not ‘Applying for a licence’
- questions
- technical terms unless you’ve already explained them
- ‘introduction’ as your first section – users don’t want an introduction, just give the most important information
Single quotes:
- Use single quotes:
- in headlines
- for unusual terms
- when referring to words or publications, for example: ‘Download the publication ‘Understanding Capital Gains Tax’ (PDF, 360KB)’
Double quotes:
- Use double quotes in body text for direct quotations.
- Code snippets should have the same background grey 'colour' to differentiate from other specification content
- Use JSON in preference to XML where only one form is included
- Use colour highlighting of syntax
- Check colour used is an accessible contrast in combination with the grey background
- Include a reference to any libraries immediately before or after the code but in the main body of the page
- FHIR elements are populated with meaningful values (for example name is 'Mrs Joan Smith' not 'A Patient' or 'Patient Name’)
- Include comments to signpost the start of each resource or provide guidance on the content of a code snippet if code is in XML (or any other language which supports comments)
If corporate guidance evolves to contradict any of the following guidance, then the corporate should be applied and the guidance updated.
- The source file is stored as a Visio format where possible
- Create diagrams with Visio where possible (or a tool which can save to a Visio format)
- Output diagrams as file type .png
- Store the source file in github in [version]_diagrams-source/Visio or appropriate folder if the file is not Visio and master location https://github.com/nhsconnect/gpconnect/tree/master/_diagrams-source
- Diagrams should be before their associated text
- Where a title is appropriate for a diagram include the title as
- a caption beneath the diagram
- a heading prior to the diagram
- do not include the title within the image
- Diagrams must have alt-text which describes the diagram
- alt-text should explain to an assistive technology user who is using a screen reader either what is in the diagram or reference to further information in the body text which explains the image
- do not duplicate the title or caption
- keep the text to a sentence or two and no more than 250 characters
- Wherever practical the combination of alt-text and the text following the diagram should fully describe the diagram
- Follow accessibility guidance for the above
- Use horizontal / vertical alignment
- Use horizontal / vertical connector lines
- Include arrowheads for direction where applicable
- Dash lines for groupings
- Minimise use of colour and only use colour where it conveys meaning
- If using colour, check the colours meet accessibility standards for contrast
- Include cardinality where applicable
- Include detail in the boxes in preference to on lines
- Minimise text in the diagram and explain detail beneath the diagram as appropriate, include explanation of colour and text
- Follow / approximate to UML Class Diagrams
- As per relationship diagrams except
- Descriptions of flow on flow lines
- Text above not within the lines
- Label groupings within the group boxing and at the top
- Follow / approximate to UML Sequence Diagrams
When you have added an image to the specification consider trying the following test: If you couldn’t see the image does the section where the image is still make sense with just the heading, alt-text, caption and body text?