Technical content A to Z

The technical content style guide covers the style, structure and terms you should use when writing content for technical users on 天美影院.

About the technical content style guide

It鈥檚 important that teams in government explain their technology clearly and concisely.

There鈥檚 a wide variety of people in government working on technical content that鈥檚 published on 天美影院, external sites like the , GitHub and beyond. A full technical style guide helps make technical content more consistent and usable across government.

Check the 天美影院 style guide first for style conventions that apply to all content.

Background

This style guide builds on:

  • existing 天美影院 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

You can search the style guide by:

  1. Selecting 鈥榮how all sections鈥�.
  2. Pressing Ctrl+f on your keyboard if you鈥檙e using a PC or 鈱�+f if you鈥檙e using a Mac.
  3. Typing the word or search term that you鈥檙e 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.

础听

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 you鈥檙e checking
  • {REFUND_ID} with the ID of the refund you鈥檙e 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 header 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 鈥榦ption鈥�
  • field for API response items, not 鈥榲ariable鈥�
  • object, not 鈥榙ictionary鈥� or 鈥榓rray鈥� - 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 鈥榶ou do not need鈥� (which is ambiguous) or聽 鈥榶ou can leave out鈥�.

API requests

Use 鈥楢PI request鈥� not 鈥楢PI call鈥�.

Tell users they can 鈥榠nclude鈥� a parameter in an API request, not that they can 鈥榮upply鈥� a parameter.

B

bold

Only use bold in text from interfaces.

breaking changes

鈥楤reaking 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 鈥榗hoose鈥� where there鈥檚 a genuine choice (like 鈥榗hoose what time you want your appointment鈥�) and 鈥榮elect鈥� when you鈥檙e indicating the appropriate response (like 鈥榮elect 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 :

  • 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:

  • 鈥榶ou must鈥� for a requirement
  • 鈥榶ou should鈥� for a recommendation
  • 鈥榶ou can鈥� for an option or possibility

Do not use:

  • it may be possible to - use 鈥榶ou can鈥�
  • you may want to - use 鈥榶ou can鈥�
  • where possible you - use 鈥榳here you can鈥�

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

credential issuer

Write 鈥榗redential issuer鈥� the first time you refer to a credential issuer. You can then use 鈥榠ssuer鈥� throughout the content.

Do not abbreviate 鈥榗redential issuer鈥� to 鈥楥I鈥� or 鈥楥RI鈥�.

CSS

Do not expand the acronym.

custom

We use this to mean 鈥測our own鈥�, for example in:

  • add a custom paragraph
  • add custom metadata

D

data type

Not 鈥榙atatype鈥�.

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 鈥榯he data is accurate鈥� not 鈥榯he data are accurate鈥�.

Digital Marketplace

Upper case聽

disable

See turn on

domain name

Lower case

Domain Name System (DNS)

Upper case

诲辞飞苍迟颈尘别听

One word, lower case.聽

E

elements

For example:

Using the correct elements in your HTML helps users of assistive technologies navigate through your pages.

example code

Before you give example code, describe what it does or how to use it, for example: 鈥楻un the following code to鈥︹��

enable

See turn on.

existing technology

Be clear whether you mean the user鈥檚 existing technology, existing third-party technology or something else.

F

filename

Not 鈥榝ile name鈥�.

fix

Not 鈥榓ddress鈥�.

folder

Not 鈥榙irectory鈥�.

follow the guidance on

For example: follow the guidance on [naming and registering government websites] (link).

frontend

Not 鈥榝ront-end鈥�.

G

get

Use instead of 鈥榬eceive鈥� for API responses, emails and so on.

get started

Not .quickstart. or .quick start. - words like 鈥榪uick鈥� can demoralise users if they do not find the task quick.

Git

Capital 鈥楪鈥� (as used on ), unless it鈥檚 the git command within code.

GitHub

Capital 鈥楪鈥�, capital 鈥楬鈥� - as used on the .

Google Chrome

Not 鈥楥hrome鈥�.

天美影院 Design System

Upper case.聽

天美影院 Forms

Upper case.聽

天美影院 One Login

Upper case.聽

天美影院 Pay

Upper case.

天美影院 Platform as a Service

Write out in full for first mention, then 天美影院 PaaS.

GraphQL

One word.

H

hackers

Use 鈥榟ackers鈥� instead of 鈥榓ctors鈥� or 鈥榟ostile actors鈥�.

For example, 鈥楽et a password that hackers cannot guess鈥�.

HTTP status codes

For example, a 200 HTTP status code. Use code styling for the status code.

HTTP Strict Transport Security (HSTS)

Write out in full on first mention, then HSTS.

I

Identity and Access Management (IAM)

Write out in full on first mention, then IAM.

Internet Explorer

Not 鈥業E鈥�.

iOS

Lower case i, capital OS.

ID

Use 鈥業D鈥� or 鈥榰nique ID鈥�, not 鈥榠dentifier鈥�. Do not expand the acronym.

information

  • store information
  • share information, not 鈥榚xchange鈥�
  • get information, not 鈥榓ccess鈥�
  • handle or contain information, not 鈥榟old鈥�

IP

Do not expand the acronym.

J

JavaScript

Capital J, capital S.

JAWS

Not 鈥楯aws鈥�.

L

legacy

Make sure you explain what you mean by legacy.

For example: 鈥楪overnment uses a lot of older technology that鈥檚 tied into costly contracts. These technologies are known as legacy systems.鈥�

M

macOS

Lower case m.

meet needs

Not suit needs.

microservices

Not micro services or micro-services.

Mozilla Firefox

Upper case.

N

National Cyber Security Centre (NCSC)

Upper case.聽

NVDA

NonVisual Desktop Access. Expand the acronym on first use, and consider linking to www.nvaccess.org/about-nvda/ or GDS documentation that explains its use.

O

onscreen

One word.聽

Open Standards Board

Upper case.

open standards

Lower case. For example: 鈥榰se open standards鈥�, or 鈥榝ollow open standards principles鈥�.

P

PHP

Do not expand the acronym.

placeholders

Use < CAPS_WITH_UNDERSCORES_INSIDE_ANGLE_BRACKETS > for placeholders in sample code, and explain the placeholder under the code sample. For example:

```

Authorization: < API_KEY >

```

Replace API_KEY with the API key we sent you.

problems

Not 鈥榠ssues鈥� or 鈥榙efects鈥�.

Progressive web apps (PWAs)

Expand the acronym on first use.聽

Python

Upper case.聽

R

render

Use for HTML.聽

For example: 鈥業f the CSS or JavaScript fails, your user鈥檚 browser still renders the HTML correctly.鈥�

REST

Upper case. Do not expand the acronym if you鈥檙e writing for API developers.

Use 鈥榓 REST API鈥� instead of 鈥榓 RESTful API鈥�. If you need to, include RESTful in brackets after the first use of REST. For example: 鈥極ur API follows REST principles (it鈥檚 鈥楻ESTful鈥�)鈥�.

Ruby

Upper case.聽

Ruby on Rails

If you say Ruby on Rails (鈥楻ails鈥�) the first time, you can use just 鈥楻ails鈥� afterwards.

S

screen reader

Not 鈥榮creenreader鈥�.

service

Avoid 鈥榦nline service鈥� unless you鈥檙e distinguishing it from other kinds of service.

set up

Not 鈥榠nstantiate鈥�, 鈥榮pin up鈥� or 鈥榮tand up鈥�.

For example: 鈥楽et up a server by鈥︹��

smoke test

Lower case.聽

SOAP

Do not expand the acronym if you鈥檙e writing for API development teams.

SQL

Do not expand the acronym.

T

(a) terminal

Not 鈥榯he command-line鈥� or 鈥榯he command-line interface鈥�, or 鈥楾erminal鈥� (which is the macOS terminal specifically).

test

Ask users to 鈥榬un鈥� a test, not 鈥榗onduct鈥�, 鈥榚xecute鈥� or 鈥榩erform鈥�.

test environment

Not 鈥榩rototype environment鈥� - user research shows this causes confusion.

third parties

For conciseness use only 鈥榓 third party鈥� instead of 鈥榓 third-party organisation鈥�.

Technology Code of Practice (TCoP)

Upper case. Write out in full for first mention, then use TCoP.

turn on

Use:

  • 鈥榯urn on鈥�, not 鈥榚nable鈥�
  • 鈥榯urn off鈥�, not 鈥榙isable鈥�, 鈥榤ute鈥� or 鈥榮ilence鈥�

U

uptime

One word, lower case.聽

V

verifiable credential (VC)

Lower case.聽

version

To avoid ambiguity, use:

  • the latest version
  • the latest stable version
  • the previous version
  • an earlier version
  • a later version

VoiceOver

One word.聽

W

Web Content Accessibility Guidelines (WCAG)

Use the full name the first time on a page. Where you need to, specify the version, for example: 鈥淧ublic sector websites and applications must meet the Web Content Accessibility Guidelines (WCAG) version 2.1 AA standard鈥�.

Words to avoid

  • action as a verb - use 鈥榙o鈥�
  • action as a noun - use 鈥榯ask鈥�
  • allow - use 鈥榣et鈥�
  • assets - use 鈥榝iles鈥� or 鈥榙ocuments鈥�
  • consult - use 鈥榗heck鈥�
  • detail (as a verb) - use 鈥榚xplain鈥� or 鈥榯ell鈥�
  • easy or easily聽 - this can demoralise users if they do not find it easy
  • enable - use 鈥榟elp鈥�
  • ensure - use 鈥榤ake sure鈥�
  • examine - use 鈥榗heck鈥�, 鈥榓ssess鈥� or 鈥榬eview鈥�
  • fulfil - use 鈥榤eet鈥�
  • in order to - use 鈥榮o you can鈥�
  • inform - use 鈥榮how鈥� or 鈥榯ell鈥�
  • interrogate - use 鈥榤onitor鈥� or 鈥榯rack鈥�
  • periodically - try to be specific
  • quick - this can demoralise users if they do not find it quick
  • refer to - use 鈥楻ead more about [xxx]鈥� for an internal link or 鈥榊ou can find out how to [xxx] on the yyy website鈥� for an external link
  • regularly - try to be specific
  • requires - use 鈥榥eeds鈥�
  • should the - use 鈥榠f the鈥�
  • simple - this can demoralise users if they do not find it simple
  • take place - use 鈥榟appen鈥�, or use active voice to start with the verb
  • underlying - this can usually be removed without losing the sentence鈥檚 meaning