Content guide - DOI-ONRR/onrr.gov-site GitHub Wiki

• Introduction
  • Inclusive design principles
  • Accessibility
  • Plain Language
• Style guidelines
  • Abbreviations and acronyms
  • Alt text
  • Active voice
  • Bulleted lists
  • Capitalization
  • Differentiating text
  • Footnotes
  • Glossary items
  • Hyperlinks
  • Numbers
  • Punctuation
  • Subscript and superscript
• Language use
  • Specific words and phrases
  • Use of gender
  • Company names
• Color use in cards
  • Primary
  • Secondary
  • Expanded
• Processes and checklists
• Additional resources

This content guide builds on the 18F Content Guide and the Conscious Style Guide.

We generally follow the Chicago Manual of Style.

When updating or adding content, add the "Content" label to your Github issue. Also add the "Enhancement or "Maintenance" label, based on the context of the changes being made.

Not all corners of the internet are accessible to everyone. We design inclusively to communicate to users that we want them to be able to use our services regardless of ability level. It says a lot to someone with deteriorating eyesight when you go out of your way to include them.

But what is inclusive design?

Our approach to inclusive design is simple:

We want to ensure ONRR.gov is accessible and welcoming to everyone who wants to use it.

To that end, we plan, structure, and build our content with inclusivity in mind through the whole process. Visual ease of use is one area of focus, so we design for colorblindness as well as the full spectrum of visual impairment.

We also design with reading level in mind. We use the free Hemingway Editor to check reading levels before publishing, and if text is above a tenth-grade reading level we simplify it. Additionally, we design with a focus on gender inclusion and generally avoid specifically gendered words and phrases.

We have written accessibility guidance

In designing the site for maximum usability, we keep cognitive disabilities in mind. Users with cognitive impairments can be limited in the way and manner they receive information from the web.

Stress and anxiety are often intensified when users fill out forms; onrr.gov does not ask users to fill out forms. To ensure accessibility for users with cognitive disabilities, we follow federal plain language guidelines. Specifics are listed below.

• A core part of accessibility is plain language. We follow the federal plain language guidelines, some of which are listed below. Take some time to read through the guidelines, and keep them in mind as you write.

• Write for your audience. The first rule of plain language is: write for your audience. Use language your audience understands and feels comfortable with. Know the expertise and interest of your average reader, and write to that person. We aim for a grade ten reading level on revenuedata.doi.gov.

• Organize the information. Organization is key. Start by stating your purpose and the bottom line. Lay things out in a logical order. Use lists for visual clarity. Put the most important information at the beginning and include background information (when necessary) toward the end.

• Choose your words carefully. Words matter. They are the most basic building blocks of written and spoken communication. Don’t complicate things by using jargon, technical terms, or abbreviations without a full title. Choose your words carefully and be consistent in your writing style. Word choice is an important part of communicating clearly.

• Be concise.

• Keep it conversational. Verbs are the fuel of writing. They give your sentences power and direction. They enliven your writing and make it more interesting. Verbs tell your audience what to do. Make sure it’s clear who does what.

• Design for reading. We want our writing to help people get information, comply with requirements, and conduct research with the least possible burden. Dense, cluttered writing deters people from taking the time to read.

• For acronyms that are more than three words long or used more than three times on a page, use the full term on first mention on every page – with the acronym in parentheses – and use the acronym on subsequent mentions.
• For acronyms that are only used once or twice on a page, or are very short, do not use the acronym.
• Do not include the definite article ("the") in front of abbreviated government agencies (use DOI, not the DOI).
• Try to limit the use of acronyms, especially several in a row. If you are writing in the voice of an agency or bureau – and the origin of that voice is obvious to users – write 'we' instead of the distant and formal acronym.
• Plurals of acronyms and initialisms are indicated with an s without an apostrophe. UCAs, not UCA's. Apostrophes denote possession, not plural form.

Active voice makes it clear who is supposed to do what. It eliminates ambiguity about responsibilities. Passive voice obscures who is responsible for what and is one of the biggest problems with government writing. Don’t confuse passive voice with past tense.

In an active sentence, the person or agency that’s acting is the subject of the sentence. In a passive sentence, the person or item that is acted upon is the subject of the sentence. Passive sentences often do not identify who is performing the action.

More than any other writing technique, using active voice and specifying who is performing an action will change the character of your writing.

We cover alt text in our accessibility guidance

• When each item is a fragment, no comma or period is required.

• When each item is a complete sentence, use a period following every list item.

• When listing single items, use lower case (unless the item is a proper noun), for example:

  • oil
  • natural gas

Much of the content on the site is in markdown. Markdown will auto-generate your ordered list (1, 2, 3...) when you list them each starting with 1. For example:

1. a thing
1. another thing
1. yet another thing

This will render as:

1. a thing
2. another thing
3. yet another thing

This behavior is useful, especially if the list changes over time. Without this behavior, if you needed to add an item in the second position, you'd need to manually reorder every number thereafter (since you'd now have two number 2s!). By numbering each item with 1., and letting markdown do the work for you, you can add to or edit the list without manually reordering the rest of the list.

For this behavior to work, the numbers cannot be separated by other elements. This auto-ordering behavior will only work if the list items follow each other without other elements in between (such as an unordered list).

• Generally follow the Chicago Manual of Style for its title case guidance
  • Use the Title Case Converter with "Chicago" selected to output the correct format
  • Tricky cases include "Revenue from Natural Resources on Native American Land." (← This is Chicago style, while AP style would capitalize "From" in the title.)
• Use title case for headings (h1) and subheadings (h2–h5), including subheadings in cards. Use title case for tab headings and table headings as well.
• Use sentence case for accordions.
• Use title case for tabs and breadcrumbs across ONRR.gov.
• When linking to documents, use title case for documents hosted on ONRR.gov. For external documents, use the case provided by the host of the document. To do this, visit the externally hosted document and follow the styling used on the page title.
• Unless starting a sentence, do not capitalize “the” before a proper noun. For example: the Department of the Interior.
• Do not capitalize the words federal, tribe, tribal, state, county, or borough unless part of a full proper name.
• In the phrase "individual Indian mineral owners," capitalize Indian because it is a proper noun, but do not capitalize the rest.
• Capitalize the titles of taxes (e.g., Coal Excise Tax).

On occasion, you will need to differentiate text within a paragraph. One example of this is a bill's regular text, along with amendments and corrections (for example, the updates to FOGRMA).

To do this:

• Text #1, the main text, is kept as regular text. It is not bold or italic and is black in color.
• Text #2 is blue and bolded #00008B
• Text #3 is dark green and italicized #006400

We use blue and dark green for two reasons. Firstly, there is sufficient contrast from black text to both blue and dark green for most people to see the difference. Secondly, there are two types of colorblindness: red/green and blue/yellow. Using green and blue prevents overlapping both types of colorblindness, and helps more people access and understand the text.

Avoid using footnotes if another pattern can be used to achieve the same or similar results. If the footnote is a URL linking to the source of the information, simply link in the main text to the source instead of using a footnote. If the footnote provides contextual or explanatory text, link to the text elsewhere, if possible. If the footnote content is a definition of a term – especially if the term is used elsewhere on the site – add the term to the site's glossary instead of using a footnote.

• Do not include a period at the end of the citation.
• Use p. for page numbers, not pg.
• Use Ibid. to indicate that a reference is the same as the prior note.

• Balance the user benefit of using multiple glossary terms with the overall readability of the text. In other words, multiple glossary terms in a paragraph may make that paragraph more difficult to read, as the pattern adds an underline and icon for each instance.
• For most terms with associated acronyms or abbreviations, include the full term and abbreviation in the term listing (e.g. Multi-Stakeholder Group (MSG)).
• In general, we don't define agency names, but for acronyms commonly used to refer to agencies that may be unfamiliar to users, we do define the acronym. In those cases, use the acronym as the full term listing (e.g. OSMRE) but spell out the full agency title within the term definition.

We cover links in our accessibility guidance.

• Write out “million” and “billion” (e.g., $2.4 billion).
• Spell out numbers under ten in running text, as well as ordinals (e.g., "third").
• Do not start a sentence with a number.
• Use numerals to represent all numbers over ten, and any numbers representing data (e.g. in automatically-generated sentences, charts, or tables)
• Use the % sign instead of spelling out "percent."
• 10-day is fine for numbers that take the form of compound adjectives. Using the number in this context is more concise and recognizable than spelling the number out.

• Use the Oxford comma. The Oxford comma differentiates between items in a list and has legal application. For example, "resources, lands and waters" has a different meaning than "resources, lands, and waters."
• Avoid using ampersands and slashes. Only use an ampersand when it is part of a proper noun or official name.
• Add a single space after each period.
• Punctuate imperative sentences (e.g., 'Help us improve this website.'), unless the imperative sentence is a call-to-action link ('Learn more about this thing →'). Punctuation on imperative links can appear stylistically messy and be perceived as unnecessarily demanding or rude by users.

Use <sub> and <sup> tags for subscript and superscript when possible (e.g., CO₂) except when writing data documentation. In that case, represent the format the same way it's presented in the data (e.g., CO2).

Alaska Native, not Alaskan Native

Congress and U.S. Congress, capitalize when used as a proper noun, do not capitalize "congressional"

dataset, not data set

department, not dept.

EITI Standard

Energy Information Administration, not Energy Information Agency

Environmental Assessment

Environmental Impact Statement (EIS): don’t capitalize site-specific or programmatic preceding EIS

Executive Summary

extractive industries, not extractive industry, extractives industry, extractives industries, or the extractive industries

fair market value, not fair-market-value

federal (adj.)

federal lands and waters: when discussing both, don't abbreviate to federal lands

forests, not timber

GOMESA, not GoMESA or gomesa

general fund, unless referring to the federal General Fund of the Treasury

government: do not capitalize

hardrock minerals, not hard rock minerals

Independent Administrator: include glossary link on first mention, and avoid using IA unless it's mentioned many times on one page

Indian is a term with specific legal and policy meanings. ONRR.gov uses the term Indian to refer to specific policies, regulations, committees, etc.

lease holder, not lessee

Margin of Variance

Multi-Stakeholder Group (MSG): always spell out on first use

natural resource, not resource, sector, or extractive

• the three broad categories of natural resources are: fossil fuels, renewables, and nonenergy minerals
• nonenergy minerals may refer to hardrock mining or locatable hardrock mining for specificity
• "product" or "commodity" may be used to refer to more specific products that result from natural resource extraction (e.g., "natural gas liquids")

nonenergy instead of "non-energy"

offshore or federal waters, (not federal lands or federal sealands) or the Outer Continental Shelf

Outer Continental Shelf: avoid OCS so the reader doesn’t think it’s a government agency or law

personal income tax, not individual income tax

reclamation, not remediation

revenues refers to Department of the Interior revenues from extraction on federal lands and waters

rights-of-way for plural usage instead of "right-of-ways" or "rights of way"

state

subnational, not sub-national

surface mining or subsurface mining, not underground mining (when discussing types of mines, “open pit” and “underground” are acceptable)

tribe and tribal, not Tribe and Tribal, unless referencing a specific tribe (a proper noun)

U.S., not US. Abbreviate except on the homepage and site header.

U.S. government

USEITI: no periods or spaces

north, south, east, west: Do not capitalize directions except when referring to specific regions (e.g., "the West")

As per President Biden's Executive Order on Preventing and Combating Discrimination on the Basis of Gender Identity or Sexual Orientation it is the policy of the Office of Natural Resource Revenue to make products and services as inclusive and accessible as possible.

To that end, it is our policy to minimize the use of gendered pronouns, "he, she, his, hers, etc." in official communication products. Gender neutral options include:

• reporter/the reporter
• mineral owner/the mineral owner
• individual/the individual
• the company
• we
• one
• they

• ASARCO LLC
• Chevron Corporation
• ExxonMobil Corporation
• Freeport-McMoRan Inc.

We use cards on the site to draw the user's attention to different options available on the page, like contacts cards or links going off site. Different cards contain different information. Primary is used for most cards, secondary is used for contact information, and announcements are accented with yellow.

Primary is used to accent the vast majority of cards, with the exception of contact information and announcements. Primary HTML Hex values are:

• Dark - 000051
• Mid - 1A227E
• Light - 534AAE

Secondary is used to accent contact information cards. Secondary HTML Hex values are:

• Dark - 004A74
• Mid - 0076A3
• Light - 52A5D4

Currently the only expanded color on the site is Yellow, which is used to accent announcements. Yellow HTML Hex values are:

• Dark - 825C100
• Mid - B6890F
• Light - ECB947

How to Update ONRR.gov

• The U.S. Government Printing Office style manual
• The Conscious Style Guide
• plainlanguage.gov