Update UGRC style sheet

[steveoh]

Benefit

The current UGRC style sheet needs to be updated and be more visible. Our policy and procedure pillar is a good fit.

We need to come to identify and come to consensus on spelling, capitalization, etc of common terms and phrases on our website.

e.g.

1. LiDAR ZIP Code webmap base map
2. table feature class feature layer
3. attribute field column

Acceptance Criteria

• [ ] Perform final review of the new UGRC Style Guide Draft.
• [ ] Update Style Sheet PDF
• [ ] feat: introduce a style guide #2996

[gregbunce]

what are base maps? (just kidding, ignore this)

[gregbunce]

most folks use ZIP Code

[gregbunce]

I vote for lidar

[steveoh]

most folks use ZIP Code

can we use that if it's trademarked? 🤪

Merriam Webster and chicago unsurprisingly don't agree with your opinion.

Let's plan on a meeting, ideally including @miriamseely, to identify the common items and then we can rock paper scissor or kick box to pick one.

I vote for lidar

I think Rick already chose a spelling but we haven't documented it yet.

[miriamseely]

I agree a meeting would be good! I have an odd schedule but can generally meet weekdays 4:30pm onward, is there a time there that works for everyone? If I'm not able to attend, I can certainly work with the style guide document to implement the correct language in the metadata.

[gregbunce]

4:30 works for me. Can we look at a date sometime after June 10?

[miriamseely]

How does this Wednesday (6/19) at 4:30 sound?

[steveoh]

I might be a bit late but i can make it.

[gregbunce]

could we bump this to either Thursday the 20th, Monday the 24th or Tuesday the 25th?

[miriamseely]

Monday 6/24 or Tuesday 6/25 both work for me!

[miriamseely]

General Style Guide Notes

• Avoid using “here” and “this” links. Say “you can read more about this on our blog” not “you can read more about this here.”
• Rather than “six months” we say semi-annually
• Capitalize “State” when referring to the political entity, and use lowercase “state” when referring to the geographical location
• Base map not basemap
• Spell out numbers one through ten
• Always use the Oxford comma
• Use "whether" if there are only two possible options. Use "if" in cases where you don't know how many options there are.
• Active voice instead of passive voice
• Tone should be: interesting, approachable, and entertaining
• Items in a bullet point list should all end in a period, or none of them should end in a period. Don’t have a mix of complete and incomplete sentences in a list (either they are all complete, or none of them are)
• Data are plural, but dataset is singular
• File names are always lowercase and words are separated by underscores or hyphens
• Refer to GIS line data as polyline data
• Spell out the acronym the first time it appears on a page, and then use the acronym after that

Abbreviations and Acronyms

• 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”.
• Esri not ESRI
• Lidar not LiDAR or LIDAR
• ZIP code not Zip Code
• e.g. means "for example" and i.e. means "in other words"

Questions

• Et cetera, etc., or etc?
• Try to keep lists in paragraph form (This layer includes a, b, c, and d) or in bullet point form?
• Do we use second person? “You can read more about this on our website” versus “More information can be found on our website”.
• Capitalize GIS tools such as Dissolve or Join, or keep them lowercase?
• Use contractions “don’t” and “aren’t” or separate words “do not” and “are not”?

[steveoh]

Use contractions “don’t” and “aren’t” or separate words “do not” and “are not”?

If I remember correctly, the DGO style guide recommends contractions.

[steveoh]

here are my notes from viewing the two style guides...

https://steve-gourley.notion.site/Writing-guide-77747c66b4ee43c18f63fa4624313879

[chriswnek]

Since we want the style guide to be public, current consensus is to post it to GitHub, but that can change if it becomes an issue.

[miriamseely]

Here is the current draft for the updated style guide: https://docs.google.com/document/d/1WhMfJf8T_ezVihbmyc5sUdlZKLhb4cJxa-ae44Pg9DY/edit?usp=sharing

The current plan is to gather feedback from around the office and finalize the language in this document. Then, Steve will convert this document into HTML and upload it to the website to be featured alongside our policies and procedures.

[steveoh]

https://github.com/agrc/gis.utah.gov/pull/2996

[chriswnek]

Sounds like this is close to getting to the finish line, and may just require one or two more meetings to review, finalize, and publish.