Style Guide

The style guide is adapted from the RDMKit knowledge base style guide by ELIXIR Europe

General style and tone

• Keep the tone friendly rather than formal, and use “you”. Imagine you were explaining something verbally to someone - how would you say it?
• Use short, active sentences and short paragraphs (3-4 sentences).
• Make use of headings and bullet points to break text up so it is easy to scan.
• Remember that the site is there to help people, so make it clear to the readers how the information can benefit them.
• Use the words your readers would use. Think of the terms they would use when searching for their problem, and use those terms.

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. rdm-toolkit@elixir-europe.org. Do not hide the email address behind a word or phrase like “contact us”.
• Etc. should be avoided. 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.”.
• 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. It is fine to skip levels when moving back up e.g. you can skip from level four to level two.
• -ise/-ize: use the “-ise” form.
• Life cycle: two separate words.
• 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:
  • A list of short items: introduce with a colon, start each bullet point with a capital and don’t use punctuation at the end of each bullet point:
    • Item 1
    • Item 2
  • A list of longer items following an incomplete introductory sentence (e.g. a sentence ending in a colon): each item ends with a semi colon and the final item ends with a full stop. Do not capitalise the first letter of each item e.g. This is the first part of a sentence that includes:
    • a longer item 1;
    • a longer item 2;
    • a longer item 3.
  • A list following a complete sentence (with a full stop): each item ends with a full stop and each point begins with a capital letter e.g. This a complete sentence.
    • This is item 1 of the list.
    • This is item 2 of the list.
    • This is item 3 of the list.
• Numbers: spell the numbers one to ten out. After that, write the numbers (11, 12, 13, etc.).
• Quotations: use double quotes for quotations, and single quotes for quotes within quotes.
• 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.
• Titles (the “title” in the front matter of pages): only the first word, proper nouns and acronyms are capitalised.
• Tool assembly: there are multiple tools in one assembly. The plural is “tool assemblies”.
• Training: training is an uncountable noun and cannot have a plural. You can write “training courses” and “training materials” but not “trainings”.

Language:

While the content of this webpage is intended for Norwegian research institutions, a significant portion of members in the Norwegian community have foreign backgrounds. Therefore, for the sake of accessibility, please add any contributions in English. When this page will finally be deployed, the content will be translated into Norwegian

Hyperlink styleguides:

Please use the following formatting style for all hypertext links when contributing to this page:

[display text](https://sampleurl.com "hover-over text")

In the hover-over text, please include meaningful information about the intended link, so that the end user may easily find the content in case of link rot.. In case you are referring to webpages which are often updated/changed, please include the date (“YYYY-MM-DD”) of accession.

Annotating text from other sources

There are three ways you can annotate text from other sources, to make it clear that this is your contribution:

Method 1: In-line comments

Use this method to additional information regarding the bulk of the text

<code> Use this method to additional information regarding the bulk of the text </code>

Method 2: Blockquote

This is my blockquote

> This is my blockquote

Use blockquotes when pasting text from other reseources, such as Science Europe. Add your own content as unformatted text.

Method 3: Information boxes

<div markdown="span" class="alert alert-info" role="alert"><i class="fa-solid fa-info-circle"></i> <b>Note:</b> This is my note or annotations. Please note that these boxes do not support additional formatting within them.</div>

Avoid overuse of these boxes - they are meant to grab attentiton and overuse diminishes their value.