Metroline: Style guide
- Sander de Ridder
- Meriem Manaï
The content of this page is based on RDMkit’s Style Guide and extended with styling information specific for the FAIR Metroline. Like the RDMKit, we follow the European Commission’s Web Writing Style Guide and their English Style Guide (November 2023). To check whether a newer version is available, search online for “EC English style guide”.
When considering to add new rules to the style guide, first check whether the guides mentioned above already handle this rule. If so, adopt the European rule. If not, add our own rule.
General style and tone
Friendly and conversational. Keep the tone friendly rather than formal, and use “you”. Imagine you were explaining something verbally to someone - how would you say it?
Clarity and directness. Use short, active sentences and short paragraphs (3-4 sentences). This makes the content easier to read and understand. Active sentences are more dynamic and engaging.
Readable structure. Make use of headings and bullet points to break text up so it is easy to scan, find and digest information.
Practical and beneficial. Remember that the site is there to help people, so make it clear to the readers how the information can benefit them. Focus on practical benefits and how the information solves problems or meets needs.
User-centric language. Use the words your readers would use. Think of the terms they would use when searching for their problem, and use those terms. This ensures that your content is relatable and easy to find through search engines.
Text
Acronyms. Spell them out the first time.
Ampersands. Do not use these in the main text or headings. It is fine to use them in menus, if you need to save space.
Capitals. Do not use all capitals for emphasis or in headings.
Data. Treat as singular (“Data is…”). (Whether “data” is singular or plural is contentious - see the Wikipedia article and this Guardian article.)
Dates. Use Wednesday 7 July 2021 (not Wednesday 7th July 2021, or other variations).
Datasets. Not “data sets”.
Email. Not “e-mail”.
Email addresses. Spell these out and make the email address the link, e.g. fairservicedesk@health-ri.nl. Do not hide the email address behind a word or phrase like “contact us”.
E.g. Use a comma, colon, or dash before e.g. and i.e., but no comma after them. If a footnote begins with them, they nevertheless remain in lower case. If a list begins with e.g. do not end it with etc.
Etc. Instead of etc. try using “for example” or “such as” or “including” at the start of a listing. If etc. is used, put a comma before it if it is in a list, like “A, B, etc.”. If a list begins with e.g. do not end it with etc.
FAIR Metroline. When referring to the FAIR Metroline, use a capital “M”. If possible, refer to it as FAIR Metroline and not as Metroline.
Gender. Avoid using gender-specific words like “he” or “she”.
Headings.
Only the first word is capitalised, unless other words are proper nouns.
Headings must be hierarchical. They must go down in order (level one, level two, level three) and not skip a level.
-ise/-ize. Use the “-ise” form.
Life cycle. Not “lifecycle”.
Links. Make the link text say where the link goes e.g. “the contribute page”, not “click here”. Avoid using the url as the link text.
Lists. The four basic types of list are illustrated below. In multi-level lists, follow the same rules for each level.
Lists of short items (without main verbs) should be introduced by a full sentence and have the following features:
introductory colon
no initial capitals
no punctuation (very short items) or comma after each item
a full stop at the end.
Where each item completes the introductory phrase, you should:
begin with the introductory colon;
label each item with the appropriate bullet, number or letter;
end each item with a semicolon;
close with a full stop.
If all items are complete statements without a grammatical link to the introductory phrase, proceed as follows:
introduce the list with a colon;
label each item with the appropriate bullet, number or letter;
start each item with a lower-case letter;
end each one with a semicolon;
put a full stop at the end.
If any one item consists of several complete sentences, announce the list with a main sentence and continue as indicated below.
Do not introduce the list with a colon.
Label each item with the appropriate bullet, number or letter.
Begin each item with a capital letter.
End each statement with a full stop. This allows several sentences to be included under a single item without throwing punctuation into confusion.
Numbers. Spell the numbers one to nine out. After that, write the numbers (10, 11, 12, 13, etc.).
References. Add references directly as a text with hyperlink, e.g. “According to FAIRifcation models, such as FAIRopoly, ”.
Run-in side heads. These are followed by a full stop not a colon. An example of a run-in side head is the start of this entry - “Run-in side heads.”
That/which. Use “that” when you are defining something and “which” when you are adding extra information about it e.g.:
“The cat that was on the table suddenly got up” is telling us which cat it was. It is important to the meaning of the sentence because you are not talking about any cat, just the cat on the table.
“The cat, which was sitting on the table, suddenly got up” is giving us extra information about the cat. The information is not necessary to understand the sentence. You can remove the clause and the sentence will still be clear. Clauses starting with “which” usually begin with a comma.
Training. Training is an uncountable noun and cannot have a plural. You can write “training courses” and “training materials” but not “trainings”.
Quotations. Use single quotation marks to signal direct speech and verbatim quotes, and double quotation marks for quotations within these. We are currently experimenting with the following format:
‘Start with a great quote from, for example, a paper, between single quotes.' (source as a hyperlink between parenthesis)
Graphic design
Description. Add clear a clear caption to images. Captions should be descriptive and provide context, helping the reader understand what the image represents and how it relates to the content.
How to suggest amendments or additions to this style guide
Send an email to fairservicedesk@health-ri.nl.