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, but not necessarily in lessons. 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.
The guide is a work in progress and additions are welcome. This version, compiled by Belinda Weaver, is a first draft.
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 organization 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.
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 Organization 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,
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 organization is The Carpentries. However, terminology such as ‘A Carpentries workshop …’ is acceptable.
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¶
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.
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.
first name, forename, given name¶
These terms to be used in preference to the term ‘Christian name’, which might offend non-Christians. Use first names 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., J. K. Galbraith.
foreign accents¶
If possible, use the correct accents on people’s names in any language, e.g., Sven-Göran Eriksson (Swedish), Béla Bartók (Hungarian), Phượng Nguyễn (Vietnamese).
foreign 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.
foreign words and phrases¶
Italicise these and provide accents where applicable, e.g., bête noire. In the case of frequently used foreign terms in accepted English usage, e.g., avant garde, vis a vis, vice versa, you do not need to italicise.
H¶
honorifics and titles¶
Honorifics which denote occupations, e.g., Doctor, Professor, can initially be used within text or in blog posts. Drop honorifics 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…’
Honorifics such as FRCS should not include full stops.
I¶
initials¶
Separate initials in names from each other with spaces and full stops, e.g., J. K. Galbraith.
-isation¶
not –ization, e.g., organisation, characterisation.
-ise¶
not -ize at end of word, e.g., characterise, sympathise, organise. One exception is capsize.
italics¶
Foreign words and phrases, and scientific names, e.g., Macropus rufus, Bufo marinus.
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 foreign names.
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.’
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 use the Oxford comma.
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, 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