Content guide

Ryan Johnson edited this page Aug 20, 2018 · 43 revisions

Table of contents

Introduction

General rules

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

Style guidelines

Abbreviations and acronyms

  • 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, 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).

Accessibility

  • Government websites are accessed by people with all backgrounds. It’s important to be inclusive in language and design.
  • “See” and “view” assume sightedness. Many users read websites with screen readers. Instead, use words like “show,” and “open.”
  • Avoid directional words like “above” and “below,” which hold no meaning to users reading on a screenreader.

Bulleted lists

  • 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.

Capitalization

  • Use title case for page titles and brief h1s (use sentence case if the title of a page is a full-length sentences with punctuation).
  • Use sentence case for other titles, headings, and subheadings (h2-h4).
  • Unless starting a sentence, do not capitalize “the” before a proper noun. For example: the Department of the Interior.
  • Do not capitalize the words state, county, or borough unless part of a full proper name.
  • Capitalize the titles of taxes (e.g., Coal Severance Tax, Waste Coal Tax).

Footnotes

  • 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.

Glossary items

  • 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.

Hyperlinks

  • Keep hyperlinks as content rich as possible.
  • When a term with an acronym is hyperlinked (e.g., Multi-Stakeholder Group (MSG)), only the main term should be part of the hyperlink.

Numbers

  • 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").
  • 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 are adjectives.

Punctuation

  • Use the oxford comma.
  • Avoid using ampersands and slashes.
  • Add a single space after each period.
  • Put periods at the end of each sentence in data availability tables.

Specific words and phrases

Alaska Native, not Alaskan Native

data set, not dataset

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

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

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 both corporate income taxes and DOI revenues from extraction on federal lands and waters

  • company payments and government revenues
  • corporate income taxes (never just federal revenues, since this can include DOI revenues)
  • DOI revenues (never just revenues or federal revenues, since this can include corporate income taxes)

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 pits” and “underground” are acceptable)

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

U.S. government

USEITI: no periods or spaces

West: capitalize regions (e.g., "the West")

Company names

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

Markdown syntax and maintenance notes

Glossary terms

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" }}.

Additional resources

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.