Our written content should be:

• Professional: We write in a straightforward manner that communicates the most amount of information in the fewest words possible. We use a light, steady tone that prioritizes active voice over passive voice.
• Informative: We highlight details that increase our users' understanding of the subject matter. We avoid overly complex descriptions and language that is difficult to understand.
• Approachable: Our writing speaks directly to the reader. We use “you” and “we” to convey a sense of community. We use common language that includes contractions, metaphors, idioms, and humor where appropriate.

We avoid the following in all written content:

• Sarcastic, dark, or inappropriate humor or comments
• Discouraging, insensitive, or otherwise derogatory language
• Language that expresses a lack of confidence or certainty. Rather than saying “we try to” or “we will do our best to”, we say “we will” or “we make an active effort towards”.
• In cases where we need to indicate something may or may not happen, we use strong language such as “we strive” and give update timelines of when certain information will be available. We also explain why the situation is uncertain and offer clear justifications for our lack of certainty on the situation.
• Language that must be updated frequently. For example, rather than saying “this dataset will be updated in November”, which is ambiguous and may be confusing to the reader depending on when they encounter that text, we simply say “we update this dataset as new information becomes available”.
• If we must specify a date or time, we always give the full date, including the year.

Capitalization

The following terms are always capitalized:

• State (when referring to the political entity)
• Census (as a stand-alone term)
• Names of web and mobile applications (Utah Roadkill Reporter, Raster Data Discovery)
• GIS tools found in ArcGIS Pro or QGIS (Dissolve, Join, Intersect, etc)
• When simply making a statement about a GIS operation without referring to the specific tool, capitalization is not necessary. (Example: We joined two layers to create this one, versus: We used Max Ent to create the layer)
• Names of departments, divisions, and offices
• Days of the week, months of the year, and specific holidays.
• General seasons such as “winter” or “first quarter” are not capitalized
• When referring to specific programming languages, we refer to the individual style guides of those languages. For example, the pandas style guide recommends “pandas” always be lowercase, whereas Python capitalizes the P and JavaScript capitalizes the J and S.

Numbers and units

• Spell out numbers one through ten. For larger numbers, use numerals.
• For numbers larger than one million, we say 1.5 million rather than 1,500,000.
• Spell out units of measurement. For example, we say “25 meters” rather than “25m” and “1.5 million miles” rather than 1.5 million mi.” In cases where these units of measurement will be used many times in a single piece of writing, we use standard lowercase abbreviations such as cm, m, and km.
• Units of measurement that are commonly represented as acronyms, such as mph for miles per hour or psi for pressure per square inch, are abbreviated as lowercase acronyms.
• We also abbreviate megabytes and gigabytes as MB and GB respectively. Larger units, such as terabytes or petabytes, are spelled out.

Singular vs plural

• Data are plural, but dataset and data layer are both singular
• Data are usually plural when referring to a set of data points. For example: “The data used to develop this layer were sourced from the United States Geological Survey.”
• Data is usually singular when referring to the concept of data. For example: “Palletjack helps you extract, transform, and load data for use in web maps.”
• Code can be singular or plural, depending on the context

Links

• We incorporate links as a natural part of the text. This means embedding links where possible within the sentence without calling direct attention to the link. For example:
• UGRC developed this process after several iterations. You can learn more about this process on our blog.
• We avoid “here” or “this” links, as well as links that are not embedded, such as the following:
• UGRC developed the following process after several iterations: gis.utah.gov. You can learn more here.
• Additionally, we only provide links for resources that are verified, relevant, and reliable.
• In an effort to reduce technical debt, we also avoid providing links that would need to be updated frequently.
• Links should use the https version of URLs wherever possible.

Abbreviations

• Spell out the acronym the first time it appears on a page, and then use the acronym after that. If you will use the acronym less than three times in the content, then do not use the acronym at all, simply spell it out each time. In general, only use as many acronyms as are absolutely necessary for the content.
• All acronyms are used in text without periods to separate letters. For example, “United States Census Bureau”, when abbreviated, is written as “US Census Bureau”. Other examples include “USFS” or “SGID”.
• Dates are abbreviated as Month 1, 2020. For example it would be “January 1, 2020” not “January 1st, 2020”.
• We avoid terms duration words with multiple meanings such as “biannual” and prefer terms such as “every six months” or “every three years”.