# Documentation Style Guide

In most cases, Mojaloop follows the latest edition of the Associated Press Stylebook. The following are foundation-specific guidelines which have been updated and slightly modified.

# Acronyms

Spell out all acronyms on first reference. Include the acronym in parentheses immediately after the full spelling only if you refer to it again in the document. Example: Kofi Annan, chairman of the board of the Alliance for a Green Revolution in Africa (AGRA), traveled to Nairobi this month. It was his first visit to the AGRA office.

# Ampersand

Only use an ampersand (&) when it's part of a formal name like the Bill & Melinda Gates Foundation. In all other cases, spell out and.

# Bill & Melinda Gates Foundation

Our formal legal name is the Bill & Melinda Gates Foundation. Use it on first reference. Always use the ampersand (&) and always capitalize Foundation when Bill & Melinda Gates comes before it.

Never abbreviate the foundation's name as BMGF.

Never translate the foundation name into other languages, as it is a proper noun. The one exception to this is when translating the foundation's name into Chinese, in which case translation is acceptable.

Do not capitalize foundation when the word stands alone. Example: The foundation's new headquarters will be built near Seattle Center.

Use Gates Foundation only if you are sure the context makes the foundation's identity clear. There is a Gates Family Foundation in Colorado, so we need to be careful. Example: The Bill & Melinda Gates Foundation and the Ford Foundation co-sponsored the event. A Gates Foundation staff member gave closing remarks.

The entity that manages the endowment is formally and legally known as the Bill & Melinda Gates Foundation Trust. You will not need to refer to this entity often, but when you do, write it out on first reference and refer to it as the asset trust thereafter.

# Bold and colons

Frequently I see structures (like in this very comment!) where you have introductory terms or phrases that are bolded and set apart from the contents with a colon. Should the colon also be bolded, or not? (I frequently see it done both ways.)

# Buffett

Note the spelling: two fs and two ts (i.e., Warren Buffett).

# Bulleted lists

Introduce bulleted lists with a colon when the listed items complete the lead-in sentence or phrase. Exception: never use colons in headings or subheadings to introduce bulleted lists.

Capitalize the first words of and use periods with listed items only if they are full sentences. Examples:

This is a complete sentence.
not a complete sentence

Never link items in a bulleted list with coordinating conjunctions and punctuation (semicolons or commas) as you would in a sentence-style list. In other words, never do:

this,
that, or
the other thing.

# Captions

Caption photos whenever possible. It helps people understand our work.

Write captions as single gerund (ing verb) phrases, followed by the city, state or country, and year the photo was taken in parentheses. Example: A doctor preparing a vaccine for delivery (Brazzaville, Congo, 2007)._

When writing a caption, be sure to introduce the people featured and explain what's happening in the image as it relates to our areas of focus. Be as brief as possible so you don't distract from the image or layout. Avoid verbs that state the obvious about what the photo's subject is doing (e.g., smiling, standing, and so on).

If one of the co-chairs appears in a photo with other people, be sure to identify the co-chair in the caption. Don't assume everyone knows what our co-chairs look like.

# Citations

Most fields have their own citation conventions. Adopt those used by the field in question. When citation conventions are unavailable or uncertain, follow The Chicago Manual of Style.

When a document uses both footnotes and endnotes, for the footnotes, use the following symbols:

1st note = * (asterisk)
2nd note = † (dagger)
3rd note = ‡ (double dagger)
4th note = § (section sign)
5th note = ** (2 asterisks)
6th note = †† (2 daggers)
7th note = ‡‡ (2 double daggers)
8th note = §§ (2 section signs)

Separate multiple superscript references (footnotes, endnotes) with commas, not semicolons.

# Clinical trials

Use Roman numerals when referring to clinical trial phases and always capitalize Phase. Example: The company will begin Phase III trials on the new drug this spring.

# Contact information

Use periods to separate parts of phone numbers, and begin each number with a plus sign.

Because we work with people throughout the world, omit the international access code, which differs from country to country (it's 011 in the United States). Examples: +1.206.709.3100 (United States) +91.11.4100.3100 (India)

# Copyright and trademark notice

All publications, media, and materials produced by or for the foundation should contain the notice shown below. The Legal team must approve all exceptions.

When possible, begin the trademark portion of the notice on a separate line.

# Dashes

Use dashes—those the width of a capital M—to indicate asides or abrupt changes in thought. Use en dashes—those the width of a capital N—with numerical ranges.

Do not include a space before or after a dash.

Examples: We work to make safe, affordable financial services—particularly savings accounts—more widely available to people in developing countries.

In the 2004 presidential election, 76 percent of U.S. college graduates ages 25-44 voted.

# Dollars ($)

In Global Health and Global Development materials, because more than a dozen countries use dollars, specify U.S. dollars in parentheses on first mention in a document. Example: $100,000 (U.S.). Omit the parenthetical U.S. in subsequent references to dollar amounts in the same document.

# Foundation program names

We have three programs: Global Development Program, Global Health Program, and United States Program.

Program is capitalized when used with the full name (Global Development Program), but not when used alone (The program makes grants in several areas.).

Use periods when abbreviating the name of the United States Program: U.S. Program.

GH, GD, and USP are fine for internal use, but inappropriate for external publications.

# Gates family

William Gates III is formally referred to as Bill Gates. In internal documents, use Bill—not a nickname or abbreviation.

Use Melinda Gates when formally referring to Melinda.

Use William H. Gates Sr. when formally referring to Bill Gates Sr. There is no comma between Gates and Sr. Bill Sr. is acceptable in internal documents.

Plural: Gateses. Do not use an apostrophe to form the plural of the family's name. Example: The Gateses attended the opening of the new University of Washington law building.

Possessive: The apostrophe follows Gates when you refer to something owned by either Bill or Melinda. Example: Melinda Gates' speech was well received. The apostrophe follows Gateses when you refer to something Bill and Melinda own jointly. Example: The Gateses' decision to provide free Internet access in U.S. public libraries has increased library usage and circulation overall.

You may also phrase it this way: Bill and Melinda Gates' decision to provide free Internet access …

See the Titles of people entry for the formal titles of Bill, Melinda, Bill Sr., and other leaders of the foundation.

# Hyphens

There are few hard-and-fast rules when it comes to hyphens. Generally we use them to enhance the reader's understanding.

Examples: When writing for the Bill & Melinda Gates Foundation, use real-world poverty examples to illustrate your point. When writing for the Bill & Melinda Gates Foundation, use real world-poverty examples to illustrate your point.

In the first example, the hyphen in real-world connects real and world to form a single adjective describing poverty. In the second example, the hyphen in world-poverty connects world and poverty to form a single adjective describing examples.

The meaning changes depending on the placement of the hyphen. In instances where a series of adjectives creates ambiguity about what they refer to, use a hyphen to clarify the intended meaning.

When capitalizing hyphenated words, only capitalize the first part. Example: Co-chairs Bill and Melinda Gates.

For other uses of hyphens—compound modifiers, prefixes and suffixes, fractions—refer to the Associated Press Stylebook.

# Numerals

When referring to dollar figures, spell out million and billion. Use figures and decimals (not fractions). Do not go beyond two decimal places. Example: The foundation granted .45 million to United Way.

When using numbers that have nothing to do with dollar figures or percentages, write them out if they are under 10, and use numerals if they are 10 or over. Example: Four program officers went on 13 site visits.

In cases of grammatical parallelism, parallel construction always trumps this rule. For instance: Mr. Johnson has two children, 5-year-old Kyle and 13-year-old Frances.

Never begin a sentence with a numeral. Either spell the number out or revise the sentence so it doesn't begin with a number.

# Percentages

When using percentages, write out percent (don't use %). Use numerals instead of writing numbers out, even if they're less than 10.

Example: This program accounts for 6 percent of our grantmaking.

# Photographer credits

If the foundation owns the image you are using, you don't need to credit the photographer. All images in our media asset management system are foundation-owned. If the foundation has purchased a license to use the image, you may need to credit the photographer. If you have questions about photo credit requirements, contact the Foundation Communications Service Desk.

# Plain language

We could call out a few specific constructions that are needlessly wordy. One that we frequently catch at Ripple is "in order to" instead of just "to."

# Quotation marks

Use double quotation marks for dialogue and the citation of printed sources. Limit use of scare quotes—quotation marks meant to call attention to a quoted word or phrase and distance the author from its meaning, typically because the language is specialized, idiomatic, ironic, or misused. Example: The foundation has increasingly used “program-related investments” in recent years.

# Quoted strings and punctuation

When describing exact strings in technical documentation, should punctuation (not part of the literal strings) be included in the quotation marks? For example, valid states include "pending," "in progress," and "completed."

# Scientific names

Capitalize and italicize scientific names in accordance with conventions in the scientific community. Use the full version of a scientific name on first mention and the abbreviated form thereafter. For example, use Salmonella typhi first and S. typhi for each additional reference.

# Serial commas

With lists of three or more items in a sentence, add a final comma before the coordinating conjunction and or or. Example: The foundation's three program areas are Global Development, Global Health, and the United States.

# Spacing after punctuation

Use only one space after punctuation, including periods, colons, and semicolons.

# Spelling and capitalization conventions

bed net: two words, no hyphen.

email: one word, no hyphen, lowercase.

foundation: lowercase, except as part of the full foundation name.

grantmaking: one word, no hyphen.

nongovernmental: one word, no hyphen.

nonprofit: one word, no hyphen.

postsecondary: one word, no hyphen.

Washington state: lowercase state (unless you're referring to Washington State University, the Washington State Legislature, or something similar).

website: one word, lowercase

# Titles of people

Formal titles should not be capitalized unless the title precedes a person's name or appears in a headline. Example: Co-chair Melinda Gates will speak at the Washington Economic Club this year.

Lowercase and spell out titles when they are not used with an individual's name. Example: The foundation co-chair issued a statement.

Lowercase and spell out titles in constructions that use commas to set them off from a name. Example: Bill Gates, co-chair of the foundation, commented on the grant.

# United States

Spell out United States when using it as a noun. Abbreviate it as U.S. (including periods) when using it as an adjective. In certain cases, as when referring to a person from the United States, it's acceptable to use American.

Examples: The U.S. State Department is in the United States. The foundation's U.S. Program…

# URL

Reference web addresses without the http:// as follows: www.gatesfoundation.org

← API Documentation Product Roadmap →