Skip to content

Latest commit

 

History

History
33 lines (29 loc) · 3.49 KB

Style Guide.md

File metadata and controls

33 lines (29 loc) · 3.49 KB
Raw

Integration Hub Style Guide

This document contains guidance and reference material for anyone writing content for the Integration Hub. It is intended to help ensure that the site is consistent and easy to understand for all users.

If there’s a point of style that is not covered here, check the GOV.UK style guide in particular the technical content section.

General GOV.UK guidance

The following points from the GOV.UK guidance are particularly relevant to the Integration Hub:

  • there's usually no need to say 'please' or 'please note' (source)
  • ID should be upper case (source)
  • subdomain should not be hyphenated (source)
  • URL should be uppercase (source)
  • API should be uppercase (source)
  • STRIDE is an acronym and should be uppercase (source)
  • use 'endpoint' not 'end-point' or 'end point' (source)
  • use 'select' rather than 'click' when talking about user interfaces (source)
  • use 'sign in/out' rather than 'log in/out' (source)
  • credentials are 'created' (not added/created/registered) and 'revoked' (not removed/deleted) (source)
  • bullet pointed lists should start with a lowercase letter (source)

Integration Hub specific guidance

The following terms and language are specific to the Integration Hub and should be used consistently across the site:

  • the team responsible for an application or API is referred to as the 'owning team'
  • the process of adding the details of an API, application or team to the Integration Hub for the first time is referred to as 'registering' (not 'creating' or 'generating' - these things already exist, the user is just telling us about them)
  • applications, credentials and teams are 'deleted' (not removed/unregistered)
  • users are 'removed' from teams, and APIs are 'removed' from applications (not deleted, the user or API still exists afterwards we have just removed the association)
  • we say 'your applications' and 'your APIs' to mean applications and APIs that are owned by a team of which the user is a member (no personal ownership is implied)
  • we say 'your teams' to mean teams that the user is a member of, not just teams that the user personally created
  • the live environment is referred to as 'production'. The collective term for all other environments is 'non-production'.
  • we use the term 'HoD/Backend' rather than just 'HoD' because some users may not understand the acronym on its own
  • we use the term 'search' to describe the user finding an item by entering text into the standard blue search box. This is the case whether or not the results are ordered by relevance, and whether the search happens client-side or server-side.
  • we use the term 'filter' to describe the user finding an item by narrowing down a list by selecting checkboxes