Skip to content
This repository has been archived by the owner on Nov 10, 2020. It is now read-only.

Content style guide

Jump to bottom
Ryan Johnson edited this page Dec 17, 2019 · 2 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.

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

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

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.
  • Use descriptive links instead of 'click here' or 'read more.' People using screenreaders can survey just the links on the page, and could hear "Link, click here" over and over again. Use descriptive links instead, such as 'See this year's revenue data,' instead of 'To see this year's revenue data, click here.'
  • Use semantic markup to create tables, flowcharts, and other site content, even if the original is an image. Text in images isn't accessible and often requires extensive alt text to make accessible.
  • Use alt text for all images that convey meaningful information. Alt text can be omitted in cases where images or icons are visually decorative and provide no meaningful information to the user (in those cases, you should ask if the image or icon is worth using at all).
  • Try not to publish content in the form of PDF files if there's an alternative. The content in PDF documents is not predictably structured, since they can be generated from multiple source documents using various software. PDFs comprised of scanned pages are not accessible, unless they have been processed with text recognition.

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.

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

    • oil
    • natural gas

About ordered lists

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

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).
    • 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 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 federal, state, county, or borough unless part of a full proper name.
  • Capitalize the titles of taxes (e.g., Coal Excise Tax).

Footnotes

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.

Glossary items

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

Links

  • Keep links as content-rich as possible. Use descriptive links (see the accessibility section).
  • When a term with an acronym is linked (e.g., Multi-Stakeholder Group (MSG)), only the main term should be part of the link.

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

Punctuation

  • Use the oxford comma.
  • 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.

Subscript and superscript

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

Specific words and phrases

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)

  • 'Native American' does not substitute for 'Alaska Native'
  • 'Native American' does not substitute in the case of proper names of agencies (e.g., Bureau of Indian Affairs), programs, or legislation (e.g., Indian Tribal Energy Development and Self-Determination Act)
  • 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")

Company names

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

Glossary terms

Glossary terms in GatsbyJS

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>

Notes on the glossary in GatsbyJS

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.

Glossary terms in Jekyll

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

Product framing

How we work

Measurement and evaluation

Writing & content management

Design & user research processes

Design resources

Development

Data

Archive

Clone this wiki locally