Skip to content
This repository has been archived by the owner on Oct 5, 2022. It is now read-only.

Add section 'Writing well for users' #58

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add section 'Writing well for users' #58

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 37 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,17 +22,19 @@ The generated HTML view of the catalogue can be found at https://developer.nhs.w

* [Sandbox APIs](#sandbox-apis)

* [Writing well for users](#writing-well-for-users)



## Contributing

The catalogue is in the open and we encourage contributions. So if you come across a spelling mistake or wish to add an NHS API, feel free to send a [pull request](https://github.com/nwisbeta/api-catalogue/pulls) or you can open a [issue](https://github.com/nwisbeta/api-catalogue/issues) to report it to us.
The catalogue is open and we encourage contributions. So if you come across a spelling mistake or wish to add an NHS API, feel free to send a [pull request](https://github.com/nwisbeta/api-catalogue/pulls) or you can open an [issue](https://github.com/nwisbeta/api-catalogue/issues) to report it to us.

Read our [contributing guidelines](CONTRIBUTING.md) for more information.

## Catalogue Structure

The catalogue files are structured as shown below:
The catalogue files are structured like this:

{system-id}/
├── system.yml
Expand All @@ -45,7 +47,7 @@ The catalogue files are structured as shown below:

If an API has a sandbox implementation, it will be available at: `https://sandbox.api.nhs.wales/{system-id}/{api-id}/`

Below is more detail on each of the catalogue files and guidance on the expected content and writing style.
Below is more detail on each of the catalogue files and guidance on the expected content and writing style. **

## system.yml

Expand All @@ -54,27 +56,27 @@ Information that may otherwise be repeated across all of a system's APIs can be

### short-name

A short name or abbreviation (max 10 chars) to be used as a prefix for each API title when displayed in the API catalogue.
A short name or abbreviation that is a prefix for each API title when displayed in the API catalogue (10 characters maximum).

### description

A short description (max 150 chars) of what the system does.
A short description of what the system does (150 characters maximum).

## api.yml

This file contains information used to generate a user friendly view of the API Catalogue. The aim is to provide information that allows somebody with limited knowledge of the architecture to decide whether the API may be suitable for their needs.
This file contains information used to generate a user friendly view of the API catalogue. The aim is to provide information that allows somebody with limited knowledge of the architecture to decide whether the API may be suitable for their needs.

### title

A short title (max 80 chars) that describes the purpose of the API, for example "Patient test results request and report".
You should use key words a user will be typing in when they're searching for the API.
Do not include the system name - when displayed in the API catalogue the system name will be prefixed automatically.
A short title that describes the purpose of the API, for example "Patient test results request and report". 80 characters maximum.
You should include key words a user would use when they search for the API.
Do not include the system name. When it is displayed in the API catalogue, the system name will be automatically prefixed.


### description

A short description (max 150 chars) of what the API can be used for.
The description should be written in the imperative mood, for example "Search for test results". This will keep the description to the point.
A short description of what the API can be used for. 150 characters maximum.
The description should be written with an imperative voice, for example "Search for test results". This gives users clear instruction, and helps to keep the description to the point. Keep sentences short and centred on one piece of information. It's harder for users to absorb run-on sentences with lots of information.


### overview
Expand All @@ -83,7 +85,7 @@ A structured description (max 800 chars), containing at least one sentence for e

- What the API does: A slightly more detailed description, optionally with a few specifics about data sources and formats.
- Who uses it and why: Examples of current consumers of the API and an example of their main use case.
- Where is it available: Mention here if it's only available to specific localities, specialties, etc.
- Where is it available: Mention here if it's only available to specific users, for example users in specific localities or specialties.

### owner

Expand Down Expand Up @@ -194,3 +196,26 @@ We are currently building up a sandbox environment for APIs in the catalogue, op
The sandbox can host test intances of the APIs, which can then be used in the early stages of developing integrations, client applications etc.

> NOTE: More information to follow on how to provide a sandbox instance and sample data for your API


## Writing well for users

* **Use plain English.** Even though you are writing for a specialist technical audience, you should try to use simple and straightforward language. It makes your content more accessible for all types of users, no matter their technical ability. You do not have to avoid using technical terms, but you should try to explain what they mean where appropriate. You should also expand an acronym the first time that you mention it, for example, Digital Health and Care Wales (DHCW).

* **Use short sentences.** Shorter sentences make it easier to read and absorb information more quickly, especially as most users tend to skim read. It also makes your content more accessible to users who struggle to absorb long sentences.

* **Front-load the most important information.** Decide what you'd like users to know about, and then talk about that first. This also applies to sentence structure. Use key words at the start of the sentence to capture the attention of skim readers.

* **Avoid repetition.** Your character count is limited. Try to include key words and diversify the way you describe the API to capture the different ways a user might search for it.

* **Answer users' questions with your content.** This is where conducting user research can really help. Find out what information your users would most like to know about the API and use that to shape your content.

* **Use a clear, active voice.** Avoid saying things like "we prefer it if you". Use "you should" instead.

* **Positive contractions help to keep things brief.** For example, "we're" and "you're". Negative contractions should be avoided, for example "can't" should be "cannot". It is easy for users to skim the "'t" and misunderstand important information.

* **Talk to the user.** Using "you can" instead of "users can" can help to make things clearer.

To learn more best practice tips for writing for the web, read:
* [NHS Digital content style guide](https://service-manual.nhs.uk/content)
* [Writing for GOV.UK](https://www.gov.uk/guidance/content-design/writing-for-gov-uk)