GovWire

Technical content A to Z

Government Digital Service

November 3
17:28 2023

Its important that teams in government explain their technology clearly and concisely.

Theres a wide variety of people in government working on technical content thats published on GOV.UK, external sites like the National Cyber Security Centre (NCSC), GitHub and beyond. A full technical style guide helps make technical content more consistent and usable across government.

Check the GOV.UK style guide first for style conventions that apply to all content.

Background

This style guide builds on:

  • existing GOV.UK style, content and accessibility guidance
  • evidence from user research
  • using the plainest language possible, avoiding idioms and ambiguous terms
  • existing style from user-focused style guides such as the Google developer documentation style guide

You can search the style guide by:

  1. Selecting show all sections.
  2. Pressing Ctrl+f on your keyboard if youre using a PC or ?+f if youre using a Mac.
  3. Typing the word or search term that youre looking for.

Suggest a change or addition

If you have a suggestion for a new style point, or you have evidence that an existing style point does not meet the needs of users, email technical-writers@digital.cabinet-office.gov.uk.

A

API

Do not expand the acronym for technical users.

API endpoints

Use methodname endpoint for an API endpoint. Do not include the base path. Use {CAPS_WITH_UNDERSCORES_INSIDE_CURLY_BRACKETS} for placeholder parameters in endpoints.

For example:

GET /v1/payments/{PAYMENT_ID}/{REFUND_ID}

Replace:

  • {PAYMENT_ID} with the ID of the payment youre checking
  • {REFUND_ID} with the ID of the refund youre checking

API headers

There are lots of HTTP and API headers, so use code style and the exact name of API headers, to make it clear which heading you mean. For example:

  • Authorisation header
  • Content-type header - not Content header because there are several different content headers

Example:

You must include an Authorisation` header in your request.

API key

Do not expand the acronym for technical users. Use:

  • create an API key - not generate
  • revoke an API key

API parameters and fields

Use:

  • parameter for API request items, not option
  • field for API response items, not variable
  • object, not dictionary or array - for example: If the status in the refund_summary object is available
  • key
  • value
  • key-value pair

Parameters are required or optional. Do not use you do not need (which is ambiguous) or you can leave out.

API requests

Use API request not API call.

Tell users they can include a parameter in an API request, not that they can supply a parameter.

B

bold

Only use bold in text from interfaces.

breaking changes

Breaking changes are changes to one part of your software system that may cause other parts to fail. Do not use this term without explaining it - user research shows not all technologists immediately understand what it means.

C

choose

Use choose where theres a genuine choice (like choose what time you want your appointment) and select when youre indicating the appropriate response (like select your year of birth).

Cloud First policy

Capitalise Cloud First.

Cloud Security Principles

Upper case.

code samples

Format code samples or excerpts in a fixed width font. You usually do this by adding either:

  • backticks (```) around code excerpts inside sentences
  • 3 backticks (````````) above and below code blocks

code styling

Use code styling for the following, which is based on the code styling list in Googles style guide:

  • classes, methods and functions
  • terminal commands
  • fields - names and values
  • data types
  • filenames, extensions, paths and folders
  • HTML element names
  • HTTP status codes
  • HTTP methods - for example GET and PUT
  • placeholder variables

conditions

Use:

  • you must for a requirement
  • you should for a recommendation
  • you can for an option or possibility

Do not use:

  • it may be possible to - use you can
  • you may want to - use you can
  • where possible you - use where you can

Do not use block capitals. Its an accessibility issue, and user research shows that it does not help users recognise and understand requirements.

credential issuer

Write credential issuer the first time you refer to a credential issuer. You can then use issuer throughout the content.

Do not abbreviate credential issuer to CI or CRI.

CSS

Do not expand the acronym.

custom

We use this to mean your own, for example in:

  • add a custom paragraph
  • add custom metadata

D

data type

Not datatype.

data

Use the following:

  • get data
  • store data
  • access data
  • share data - not exchange data, unless data is going both ways

Treat data as a singular noun, so use the data is accurate not the data are accurate.

Related Articles

Comments

  1. We don't have any comments for this article yet. Why not join in and start a discussion.

Write a Comment

Your name:
Your email:
Comments:

Post my comment

Recent Comments

Follow Us on Twitter

Share This


Enjoyed this? Why not share it with others if you've found it useful by using one of the tools below: