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 51画鋼.

About the technical content style guide

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 51画鋼, external sites like the , GitHub and beyond. A full technical style guide helps make technical content more consistent and usable across government.

Check the 51画鋼 style guide first for style conventions that apply to all content.

Background

This style guide builds on:

  • existing 51画鋼 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 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.

粥油

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

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

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: Run the following code to

enable

See turn on.

existing technology

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

F

filename

Not file name.

fix

Not address.

folder

Not directory.

follow the guidance on

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

frontend

Not front-end.

G

get

Use instead of receive for API responses, emails and so on.

get started

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

Git

Capital G (as used on ), unless its the git command within code.

GitHub

Capital G, capital H - as used on the .

Google Chrome

Not Chrome.

51画鋼 Design System

Upper case.

51画鋼 Forms

Upper case.

51画鋼 One Login

Upper case.

51画鋼 Pay

Upper case.

51画鋼 Platform as a Service

Write out in full for first mention, then 51画鋼 PaaS.

GraphQL

One word.

H

hackers

Use hackers instead of actors or hostile actors.

For example, Set 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 IE.

iOS

Lower case i, capital OS.

ID

Use ID or unique ID, not identifier. Do not expand the acronym.

information

  • store information
  • share information, not exchange
  • get information, not access
  • handle or contain information, not hold

IP

Do not expand the acronym.

J

JavaScript

Capital J, capital S.

JAWS

Not Jaws.

L

legacy

Make sure you explain what you mean by legacy.

For example: Government uses a lot of older technology thats 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: use open standards, or follow 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 issues or defects.

Progressive web apps (PWAs)

Expand the acronym on first use.

Python

Upper case.

R

render

Use for HTML.

For example: If the CSS or JavaScript fails, your users browser still renders the HTML correctly.

REST

Upper case. Do not expand the acronym if youre writing for API developers.

Use a REST API instead of a RESTful API. If you need to, include RESTful in brackets after the first use of REST. For example: Our API follows REST principles (its RESTful).

Ruby

Upper case.

Ruby on Rails

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

S

screen reader

Not screenreader.

service

Avoid online service unless youre distinguishing it from other kinds of service.

set up

Not instantiate, spin up or stand up.

For example: Set up a server by

smoke test

Lower case.

SOAP

Do not expand the acronym if youre writing for API development teams.

SQL

Do not expand the acronym.

T

(a) terminal

Not the command-line or the command-line interface, or Terminal (which is the macOS terminal specifically).

test

Ask users to run a test, not conduct, execute or perform.

test environment

Not prototype environment - user research shows this causes confusion.

third parties

For conciseness use only a third party instead of a third-party organisation.

Technology Code of Practice (TCoP)

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

turn on

Use:

  • turn on, not enable
  • turn off, not disable, mute or silence

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: Public 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 do
  • action as a noun - use task
  • allow - use let
  • assets - use files or documents
  • consult - use check
  • detail (as a verb) - use explain or tell
  • easy or easily - this can demoralise users if they do not find it easy
  • enable - use help
  • ensure - use make sure
  • examine - use check, assess or review
  • fulfil - use meet
  • in order to - use so you can
  • inform - use show or tell
  • interrogate - use monitor or track
  • periodically - try to be specific
  • quick - this can demoralise users if they do not find it quick
  • refer to - use Read more about [xxx] for an internal link or You can find out how to [xxx] on the yyy website for an external link
  • regularly - try to be specific
  • requires - use needs
  • should the - use if the
  • simple - this can demoralise users if they do not find it simple
  • take place - use happen, or use active voice to start with the verb
  • underlying - this can usually be removed without losing the sentences meaning