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.

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

downtime聽

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: 바카라 사이트�바카라 사이트 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