# IOI House Style Guide

Last updated: 2024-05-23
URL for this page: https://hackmd.io/@investinopen/house-style
URL for this site: https://hackmd.io/@investinopen/how-we-work

## What is a House Style Guide, and why do we have one?
This House Style Guide outlines how IOI's external documents and content should be written.

By adopting and using this guide, we maintain consistency across our various communication channels and types of content. This consistency helps us build trust with our audience. This guide should also save us time by providing one place to look for answers related to writing.

This style guide also aims to increase the accessibility and inclusivitiy of our work. For example, through prioritizing plain language and putting information in a logical order, we strive to enable everyone to find the information they need and understand what they find.

This is a living document. Questions help it grow. :seedling:

## Spelling and Wording

### Spelling
IOI uses **Oxford English** spelling, which is British spelling in combination with the suffix `-ize` (rather than `-ise`) for about 200 verbs, e.g. organize, realize. For more about Oxford English spelling, see [ISO's house style](https://www.iso.org/ISO-house-style.html#iso-hs-s-text-r-s-spelling) and the [Oxford English page on wikipedia](https://en.wikipedia.org/wiki/Oxford_spelling). You can use the [Oxford Learner's Dictionaries](https://www.oxfordlearnersdictionaries.com/definition/english/organize?q=organize) to check the spelling of specific words.

### Names of countries, territories and regions
- We use the names and definitions in the [United Nations geoscheme](https://en.wikipedia.org/wiki/United_Nations_geoscheme) when referring to regions, subregions and sub-subregions.
- We avoid using the phrases "Global North" and "Global South", except where they are used by the source.
- When referring to countries, we use [UN Member States names](https://www.un.org/en/about-us/member-states), so `Viet Nam` instead of `Vietnam`, and `Democratic People's Republic of Korea` instead of `North Korea`.
- Exceptions:
- the United States (US) can be used in place of the United States of America;
- the United Kingdom (UK) can be used in place of the United Kingdom of Great Britain and Northern Ireland.

### Use diacritical marks
Please don't drop accents and diacritical marks where they should be present, including on people's names. This helps make clearer who or what you are referring to.

## Punctuation
- Do not use the ampersan (&) in ordinary text. Use the word "and" instead.
- Exceptions:
- "&" can be used when it is used by a source, e.g. proper names or other intentional tiles.
- "&" can be used when there is a limit on number of characters, e.g. in a tweet.

- Use [Oxford commas](https://en.wikipedia.org/wiki/Serial_comma)

- Hyphens:
- Compound nouns are usually presented as a single word with no hyphens or as two separate words, e.g. roadmapping, decision making
- Compound adjectives that modify the noun are hypehnated when they come before the noun, e.g. open-source software, community-owned infrastructure, long-term needs, non-profit organization.
- Do not use a hyphen when the compound comes after the noun, e.g. “The figures were up to date”, “changes in the medium term”, “the result is well known”.
- Do not hyphenate compound adjectives when the first word is an adverb ending in -ly, e.g. newly discovered planet, finely ground powder.
- Regarding "for-profit" and "non-profit" - use these forms adjectivally and hyphenated wherever possible (e.g. "for-profit entity"). The noun "nonprofit" may be used without a hyphen (e.g. "The organization was formed as a nonprofit."). Avoid using the noun version of "for-profit" because of the infelicity of the form "forprofit"; try to use it with a noun (e.g. "for-profit organization") wherever possible.

- En dashes (–)
- Use en dashes in ranges, e.g. pages 7-10.

- Em dashes (—)
- Use spaced em dashes to indicate parenthetical information, highlight a list, or mark a turn in thought, e.g. the research lifecycle — from designing experiments to publishing.

- Quotation marks
- Use double quotation marks. For quotes inside quotes, use single quotation marks.
- When the quote is within a sentence and the punctuation mark is part of the quote, keep it within the quotation marks. E.g. The question that was asked was "Did you answer my question?"
- When the quote is within a sentence and the punctuation mark is not part of the quote, keep it outside the quotation marks. E.g. The participants reflected that it was "inspiring" and "encouraging".

- Footnotes
- Footnote numbers go AFTER punctuation (fullstops, commas, quotation marks, colons, etc.)
- Footnote numbers should not follow dashes ( — ), and if they appear in a sentence in parentheses, the footnote number should be inserted within the parentheses.

## Numbers, units, and dates
### Numbers
- Write numbers as words up to nine and use digits after that. However, exceptions can be made to improve readability.
- Be consistent within sentences, e.g. "five members of staff and fourteen members of the governance team".
- Use variety to help make the meaning clear, e.g. "Three 2-hour sessions followed by a 30-minute break".
- Write first, second, third rather than firstly, secondly, thirdly
- Use Commas as thousand separators, and periods as demical separators.
- For big numbers, e.g. millions and billions, one can spell it out fully (e.g. 154 million) or use "M" (e.g. "154M"), "B", etc.

### Units
- Where possible, use [International System of Units (SI)](https://en.wikipedia.org/wiki/International_System_of_Units) for measurements.
- Use non-SI units if the source quoted uses non-SI unit, but give the equivalent value in SI units in brakcets, e.g. 3.5 miles (5.6 km).
- For temperatures, degrees Celsius can be used instead of kelvin.
- **Currency**:
- For currency symbols shared by multiple currencies, e.g. $, specify which one it is before the symbol, at least at its first mention in the text. e.g. US$100 or HK$2000
- For unique curreny symbols, explain them on first use, unless they are very well known to your audience, e.g. the minimum wage in China is Chinese RMB (¥) 2,200 per month.
- Do not also use IBAN currency code with the currency symbols, i.e. NOT $100 USD.

### Dates
- In prose, write DD MM YYYY, with spaces and no commas, so "14 April 2022".

## Citations
- For references to a living page/project, we use a footnote with (at least) a link to the page/project's website.
- e.g. Invest in Open Infrastructure¹ is a non-profit initiative... ; corresponding footnote: 1. https://investinopen.org
- For references to formal publications, blog posts, and other articles (often with a defined date of publication and specific authors), we use in-line citations in APA style, with the reference included in full in a reference/bibliography section at the end.

## Inclusive writing
### Write in Plain English
According to the [Center for Plain Language](https://centerforplainlanguage.org/learning-training/five-steps-plain-language/), communicating in plain language allows readers to easily find what they need, understand what they find, and use that information. There are 5 steps to writing in plain language:
1. Identify, describe and write for the target audience.
2. Structure the content to guide the reader through it.
3. Write the content in plain language.
4. Use formatting to help readers see and understanding.
5. Work with the target user groups to test the design and content.

Some detailed resources on how to write in plain language:
- [Center for Plain Language](https://centerforplainlanguage.org/learning-training/)
- [plainlanguage.gov](https://www.plainlanguage.gov/guidelines/)

Some specific guidelines regarding word choices and language:
- Avoid hidden verbs, e.g. instead of "we carried out an investigation into the funding models", say "we investigated the funding models".
- Avoid noun strings , e.g. instead of "Catolog of Open Infrastructure Services expression of interest form", say "A form to express interest in the Catalog of Open Infrastructure Services".
- Avoid jargon and meaningless filler phrases, e.g. "aforementioned", "touch base".
- Use the same terms consistently - our glossary helps here.

### Write for an international audience
- Avoid idioms, colloquialisms, or slang, e.g. "hit the nail on the head", "move the needle"
- Avoid or explain culturally-specific terms, e.g. "990s", "IRs", "land-grant universities"

### Avoid ableist language
- Avoid words or phrases such as, crazy, insane, blind, cripple, dumb and others.

> :bulb: See the [Diversity Language Style Guide](https://ncdj.org/style-guide) for more examples and guidance.

### Avoid unnecessarily gendered language
- Don't use he, him, his, she or her as gender-neutral pronouns.
- Use the singular they, instead of he/she or (s)he or other such punctuational approaches.
- Don't use gender-specific pronouns unelss the person you are referring to is actually that gender.
- Be mindful of other possible sources of gendered language, e.g. use person-hours instead of man-hours, humanity instead of mankind.
- Use language that recognises gender as a spectrum instead of as a binary, e.g. different sex instead of opposite sex.

### Avoid ageist language
- Avoid referring to someone's age, unless it's relevant to what you are writing about.
- Don't use older people as substitute for novice or beginner.

### Avoid language that reinforces racial, ethinic and religious stereotypes

## Formatting

### Fonts
Our standard font is [Inter](https://fonts.google.com/specimen/Inter). This is available by default in the Google Suite.

### Titles
- Capitalize only the first word of the title, heading, and subheadings.
- EXCEPT for two-part titles— for two part titles separated by a colon, capitalize the first word of both parts of the title.

### Headings
- Use built-in headings and subheadings where possible:
- In Google Docs, select a text style on the toolbar styles menu.
- In Ghost (our content management system), use the default heading and subheading styles.
- you can also use Markdown or HTML to style headings in Ghost.
- In HackMD, use #, ##, ###, etc to style headings.
- Avoid skipping heading ranks as it creates confusion: make sure a Heading 2 is *not* followed directly by a heading 4.

### Font sizes and line spacing
More details coming in our upcoming brandbook.

### Lists
- Bullet points ending with fullstops (.), no punctuation, or semicolon (;) and fullstops (.) and all allowed - we understand that the best punctuation use depends on the list and the context.
- That being said, the punctuation on the same list should be kept consistent. That is, in the same list, don't end some bullet points with a fullstop and others without.

## References
This house style is inspired by and adapted from:
- [18F Content Guide](https://content-guide.18f.gov/our-style/)
- [Conscious style guide](https://consciousstyleguide.com/)
- [Diversity Style Guide](https://www.diversitystyleguide.com/)
- [W3C Accessibility Guidelines (WCAG) 3.0](https://www.w3.org/TR/wcag-3.0/)

## See also
* Our [Research reporting guide](https://hackmd.io/@investinopen/research-reporting) for generating research reports.
* Archived copy of this page (via the Internet Archive's Wayback Machine): https://web.archive.org/web/*/https://hackmd.io/@investinopen/house-style

---
This page first published: 2022-04-13

###### tags: `process`

---

<a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br />This work is made available under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>. Users are free to share, remix, and adapt this work. (Please attribute [Invest in Open Infrastructure](https://investinopen.org/) in any derivative work).