Content style guide - DOI-ONRR/nrrd GitHub Wiki

• Introduction
  • Plain language
• Style guidelines
  • Abbreviations and acronyms
  • Accessibility
  • Active voice
  • Alt text
  • Bulleted lists
  • Capitalization
  • Footnotes
  • Glossary items
  • Hyperlinks
  • Numbers
  • Punctuation
  • Subscript and superscript
• Specific words and phrases
  • Use of gender
  • Company names
• Glossary terms in markdown
• Additional resources

• This content guide builds on the 18F Content Guide.

• Avoid duplication. If another government agency or part of the NRRD site already has the information, link to it directly.

• For annual reports or frequently changing content, try to find landing pages instead of linking to a specific year's report

• Content in the 'How it works' section of the site should be mostly static explanatory or contextual narrative. With few exceptions, the 'How it works' section should not contain content that requires routine manual updates. In some cases, it may make sense to place variables within the content that automatically pull in data, but those figures should be reviewed for accuracy when the site data is updated.

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; revenuedata.doi.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.

We have written separate Accessibility guidance.

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.

Alt text is covered 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 page titles and h1s.
• Use sentence case for other titles, headings, and subheadings (h2–h4).
• Glossary and dictionary items are presented in title case, their definitions are presented in sentence case.
• 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, state, county, or borough unless part of a full proper name.
• Capitalize the titles of taxes (e.g., Coal Excise Tax).

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.
• For capitalization, glossary items are presented in title case. Glossary definitions are presented in sentence case.

Links are covered 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.
• Avoid using ampersands and slashes in paragraphs whenever possible. Only use an ampersand when it is part of a proper noun or official name. In titles and H1s, use ampersands to show equal pairing of either two or three items. In paragraphs below a title or H1 with an ampersand, repeat the title exactly with the ampersand to maintain continuity.
• 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

lease holder, not lessee

Margin of Variance

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

Native American, not American Indian, Indian, or tribal (unless the latter specifically refers to a tribe)

• 'Indian' is a term with a distinct meaning in legal and policy contexts. When referring to groups of people, Native American or Indigenous People is preferred.
• 'Native American' does not substitute in the case of proper names of agencies (e.g., Bureau of Indian Affairs), programs, reports, or legislation (e.g., Indian Tribal Energy Development and Self-Determination Act).
• 'Native American' does not substitute for 'Alaska Native' or 'Native Hawaiian'.
• H.R. 4238 provides legal guidance on terms.

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.

Definitions are stored in src/data/terms.yml.

To reference a glossary term in markdown, use this format:

<glossary-term>term</glossary-term>

If your referenced term in your markdown file is a variation of the term in terms.yml (for example, "bonuses" versus "bonus"), and you still want to reference the glossary definition, you can call the term.key:

<glossary-term term.key="term">variation of term</glossary-term>

GlossaryTerm is a React component, located in src/components/utils/glossary-term.js. The glossary's state is managed in a separate component, located at src/components/utils/Glossary.js.

In order for React components to be used in markdown, they must be included in hast-react-renderer.js utility. This utility is located at src/js/hast-react-renderer.js.

Definitions are stored in /_data/terms.yml.

There are 4 different variations of the markdown syntax that connects a word or phrase to the glossary:

• If displayed text exactly matches the glossary term: {{ "text" | term }}
• If displayed text differs from the glossary term: {{ "text" | term:"different text" }}
• If displayed text exactly matches the glossary term AND is followed by punctuation: {{ "text" | term_end }}. (this corrects the spacing so there isn't a strange gap)
• If displayed text differs from the glossary term AND is followed by punctuation: {{ "text" | term_end:"different text" }}.

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