The Carpentries Style Guide#
This guide aims to provide a standard reference point when questions arise about style for The Carpentries - how we would prefer people to reference us, how best to render dates and times for a global community, when to use what capitalisation, and other questions of style.
We will adhere to a similar style on our website and in other material we make widely available such as blog posts. Lesson contributors and maintainers should aspire to adhere to this style, but may prioritise making material available over style considerations. To ensure that the style guide is as widely applicable as possible, UK English spellings and usage will be used in favour of American spelling.
Please note, as outlined in section C: The Carpentries, while sounding plural, is a singular entity. Therefore, when referring to The Carpentries, verbs should also be singular, e.g., ‘The Carpentries is …’. The full and correct title for the merged organisation is The Carpentries. However, terminology such as ‘A Carpentries workshop …’ is acceptable.
A#
abbreviations and acronyms#
Generally use all capitals for initialisms, e.g., NSF, CEO, BIDS. When writing about an organisation or event within text, provide the acronym in brackets on first use, and use the acronym to refer to the organisation or event from then on. For example, ‘She was the chair of the National Science Foundation (NSF) … The NSF … ’
If an organisation is mentioned only once within a piece of text, say, in a blog post, it is not necessary to provide its acronym. Do not use acronyms without spelling these out first as country-specific acronym may be unfamiliar to members of our community.
accents#
Use on non-English words when known. People’s names, in whatever language, should also be given appropriate accents where known, e.g., ‘Arsène Lupin was a jewel thief who never got to Bogotá or Angoulême.’
adverbs#
Hyphens are not needed after adverbs ending in -ly, e.g. a hotly argued topic, a constantly evolving career, a recently published program, etc. Hyphens are needed with short and common adverbs, e.g., ever-faithful follower, ill-written script, much-quoted speech.
alphabetisation#
The lesson programs within The Carpentries, when listed together, should be listed in alphabetical order: Data Carpentry, Library Carpentry, and Software Carpentry
ampersand#
In text and blog posts, use the ampersand in organisations’ names when the organisation does so, e.g., P&O, AT&T.
apostrophes#
Indicates either a missing letter or letters (can’t, we’d, hadn’t) or a possessive (Siobhan’s script). The correct use of the apostrophe is important, as a misplacement or omission can alter a sentence’s meaning. Apostrophes are not needed in dates. Preferred form is 1990s, not 1990’s; the 70s, not the 70’s.
B#
bullet points#
Should ideally include a full stop after each one if it is not just a list of terms, i.e:
This is the first bullet point that covers a range of ideas.
This is the second that also ranges quite widely.
And this is the third and these are just examples.
But
Instructors
Trainers
Mentors
C#
capital letters and capitalisation#
titles
Render these with initial capitals, e.g., President Abraham Lincoln, Facebook’s CEO, Pope John Paul II, the Secretary-General Ban-Ki Moon.
government departments initial capitals, e.g., Department of Industry, Department of Health. Use lower case when not referring to a department by its proper name, e.g., ‘Senator Carr first led the Department of Industry. The department is now led by … ’
government agencies, public bodies, quangos
Render these with initial capitals, e.g., District Attorney’s Office, Human Rights Commission, the University of Florida. Use lower case when not referring to an organisation by its proper name, e.g., ‘She worked for the National Society of Coders. The society was founded … ’
lesson titles and episode names
Lesson titles and episodes within lessons should be rendered in Title case, i.e. all major words capitalised, e.g., Introduction to Data; Project Organisation and Management for Genomics.
names of institutions
Render these with initial capitals, e.g., Gordon and Betty Moore Foundation, Smithsonian Institute, the United Nations, the European Union.
roles
Roles within The Carpentries are always capitalised. Therefore we use Instructor, Supportive Instructor,
Trainer, Maintainer, Mentor, and Curriculum Advisor. Helper and host are not capitalised as these are not official roles.
Carpentries#
The Carpentries, while sounding plural, is a singular entity. Therefore, when referring to The Carpentries, verbs should also be singular, e.g., ‘The Carpentries is …’. The full and correct title for the merged organisation is The Carpentries. However, terminology such as ‘A Carpentries workshop …’ is acceptable.
colour#
Use adequate contrast to ensure the best readability. Colour should not be the only means of conveying information (indicating action, prompting a response, or distinguishing a visual element). Avoid using the colour combinations of red/green, green/brown, green/blue, blue/gray. Use shapes, patterns, textures, and labels to help distinguish differences. Contrast Checker from WebAIM.
commas#
Use commas to separate clauses in long sentences. ‘If the judges truly reflected on their decisions regarding the non-award of prizes in 2010, they would not find it hard to see why people objected to their choices.’
Commas can be used definitively. For example, in this sentence: ‘The developer, Sue Miller, is a keen coder,’ the use of commas indicates that there is only one developer.
Where no such definition is needed, e.g., ‘PyCon speaker Mary Clough won the award,’ no commas are needed since there are many speakers at PyCon, not just one.
A comma is also crucial to avoid ambiguity in examples such as this: ‘The report criticises the judges who have been accused of favouritism.’ A comma after ‘judges’ would have made it clear that all judges have been accused of favouritism. Without the comma, the sentence implies that only some judges have been criticised.
See also Oxford comma.
company names#
Company names are always singular, e.g., ‘Twitter is …’, ‘Amazon Web Services is …’
D#
data frames#
When referring to data frames in text, use two words, sentence case, which is the convention in the R language. If you are writing for Python, then using DataFrame (one word, upper camel case) is appropriate in line with the convention of the Python language
dates#
Our style is 21 July, 2011 (day month year).
Other renderings: ‘In the 21st century’ but ‘21st-century science’.
Use figures for decades, e.g., the 1990s, the radical 60s, etc. Do not add an apostrophe to decades, i.e. 1990s, not 1990’s; the 70s, not the 70’s.
diacritical marks#
If possible, use the correct diacritical marks on people’s names in any language, e.g., Sven-Göran Eriksson (Swedish), Béla Bartók (Hungarian), Phượng Nguyễn (Vietnamese).
E#
e.g.#
include full stops, and always follow with a comma, whether you are using the abbreviated form, e.g., or the written-out version, for example.
etc.#
Include final full stop.
F#
figures#
Always spell out in writing the numbers from one to nine. Use numerals for numbers 10 to 999,999, and thereafter go back to writing numbers out in full, e.g., one million readers, eight billion people, but when the first number is above nine, you can go back to figures for that first part, e.g., 20 million lines. Spell out ordinals from the first to the ninth, e.g., third, fifth, and thereafter use 10th, 31st, etc.
fractions#
Render as two-thirds, three-quarters, etc., but two and a half needs no hyphens.
See also figures.
full-stops#
The first character after a full-stop should be capitalised and have one space before it, rather than two.
G#
given name#
This term to be used in preference to the terms ‘first name’, ‘forename’, and ‘Christian name’. Use given name the first time someone is mentioned, but not subsequently, e.g., ‘Mary Brown came late to programming … Brown later went on to develop several well-known programs.’
Avoid using initials rather than a name, unless that is how a person is best known, e.g., N. K. Jemisin.
H#
honourifics and titles#
Honourifics which denote occupations, e.g., Doctor, Professor, can initially be used within text or in blog posts. Drop honourifics and first names after the first mention and use surname only from then on, e.g., ‘Professor Gillian Kramer teaches … Kramer has spent a lot of time…’
Honourifics such as FRCS should not include full stops.
I#
i.e.#
include full stops, does not precede a comma in British English
inclusivity#
Use inclusive language. This includes word choice that recognises the complexity of the subject matter and respects the diversity of all members of the community. Use globally accessible references, either with a more common name or a more verbose description.
Things to avoid: diminishing or dismissive language (just, simply, obviously, etc), local colloquialisms, sensory words or action words (see, hear, read, look, run, reach, listen)
images#
Include alt text on all images.
initials#
Separate initials in names from each other with spaces and full stops, e.g., N. K. Jemisin.
-isation#
not –ization, e.g., organisation, characterisation.
-ise#
not -ize at end of word, e.g., characterise, sympathise, organise. One exception is capsize.
italics#
Words and phrases in languages other than English, and scientific names, e.g., Macropus rufus, Bufo marinus.
L#
link text#
Avoid “click here”, “more”, and “read more” when embedding a link in text. Use words that describe link, not the full URL. Link up to a full sentence but avoid using longer. Use non-colour indicators such as a persistent underline to highlight link. When linking an email, use Email first name last name, instead of just the person’s name.
N#
names#
Do not use the terms Christian name, first name, or forename. Instead use given name or personal name. We will defer to people’s chosen spelling, choice of given name, punctuation, capitalisation, and name order (when known or obtainable).
See also non-English names.
non-English names#
The French (or French origin) de, d’, des, la, les or le and the Dutch van are normally lowercase when the name is fully written out, e.g., Marianne d’Alpuget, Erik van der Walden, but capitalised when written without forenames, e.g., D’Alpuget, Van der Walden.
non-English words and phrases#
Italicise these and provide accents where applicable, e.g., bête noire. In the case of frequently used non-English terms in accepted English usage, e.g., avant garde, vis a vis, vice versa, you do not need to italicise.
numbers#
Always spell out in writing the numbers from one to nine. Use numerals for numbers 10 to 999,999, and thereafter go back to writing numbers out in full, e.g., one million readers, eight billion people, but when the first number is above nine, you can go back to figures for that first part, e.g., 20 million lines. Spell out ordinals from the first to the ninth, e.g., third, fifth, and thereafter use 10th, 31st, etc.
When starting a sentence with any number, the number should be written out as words, e.g., ‘Twenty-five people attended the workshop.’ ‘Nineteen-ninety-five was not a leap year.’
numbered lists#
Like bullet points,should ideally include a full stop after each one if it is not just a list of terms, i.e:
This is the first numbered item that covers a range of ideas.
This is the second that also ranges quite widely.
And this is the third and these are just examples.
But
Instructors
Trainers
Mentors
O#
Oxford comma#
A comma before the final ‘and’ in lists. Straightforward lists (he wrote books, short stories and poetry) do not need the extra comma, but sometimes it can help the reader to know which bits go together, e.g., ‘she wrote in these genres – horror, mystery, cloak and dagger, and fantasy’, and sometimes it is essential for clarity and meaning, e.g.,
I spoke to my sisters, Olga Petrova, and Susanne De Vries (means I spoke to my sisters AND to Olga Petrova and Susanne De Vries)
I spoke to my sisters, Olga Petrova and Susanne De Vries (this wrongly implies that Olga Petrova and Susanne De Vries are the sisters in question.)
Carpentries style is to prefer the Oxford comma unless necessary.
P#
per cent#
Please spell this out in text, e.g., not as %, and write as two words, not one.
periods#
See full stops.
Q#
quotation marks#
Use single quotes at the start and end of a quoted section, with double quotes for quoted words within that section. Place full stops and commas inside the quotes for a complete quoted sentence; otherwise the full stop comes outside, e.g.,
‘Anna said: “Your style guide needs updating,” and I said: “I agree.”’ ‘Anna said updating the guide was “a difficult and time-consuming task”.’
For parentheses inside direct quotes, use square brackets, e.g., The judges said, ‘We very much liked the work of Goran [Kovacs] from Croatia’.
quotations#
Colons, rather than commas, should be used to introduce quotations from speeches or writings that run longer than a single sentence, e.g., Brown said: ‘Winning the Nobel Prize was a highlight. It will change my life. I can’t believe my luck.’
To introduce phrases or single sentence quotations, a comma is preferable, e.g., Brown said, ‘Winning the Nobel Prize was a highlight.’
R#
roles#
Roles within The Carpentries are always capitalised. Therefore we use Instructor, Supportive Instructor, Trainer, Maintainer, Mentor, and Curriculum Advisor. Helper and host are not capitalised as these are not official roles.
S#
scientific names#
Render these in italics, with the first name, which denotes genus, having an initial capital, with the second, which denotes species, written in lower case, e.g., Aedes aegypti (yellow fever mosquito), Crocodylus porosus (Saltwater crocodile), Macropus rufus (Red kangaroo).
seasons#
Avoid using seasons when discussing or announcing events, as seasons vary from hemisphere to hemisphere. What is Fall in the USA is spring in Australia. Use a month range instead, e.g., January to March, or use halves or quarters, e.g., ‘This happened in the first quarter of 2018’, ‘This is planned for the second half of the year.’
See also dates.
singular or plural?#
Corporate entities take the singular: e.g., ‘The NSF has announced … ’ In subsequent references, use a singular pronoun: ‘It will cover the Olympics.’ The Carpentries is always singular.
square brackets#
In text, square brackets are used for interpolated words in quotations, e.g., Olav Jonsson said, ‘Matthew [Brown] went to CapeTown to address a conference.’
T#
times#
Times should be rendered in UTC in a 24-hour format, e.g., 12:00 UTC, 17:30 UTC, 09:00 UTC. Do not use local zones, e.g., PDT, AEST. If you want to make times meaningful for people in a range of time zones, use the Event Time Announcer (using your UTC time and date as the basis to create the event) to create a linkable time that will render locally for each person who uses it, e.g., 20 August, 2018 22:00 UTC: https://www.timeanddate.com/worldclock/fixedtime.html?msg=Carpentries+Mentoring+Committee+Meeting+2&iso=20180820T22&p1=%3A&ah=1
V#
versus and vs#
Use versus in most written cases, but if abbreviation is necessary, use “vs” rather than “vs.”
Videos#
All videos should be captioned.