Style Guide

This is version 1.0, published December 29, 2019.

This is a personal guide for how I should write on this website – it’s intended to be a stake in the ground, but will absolutely evolve over time.

Shortcuts-specific language

  • The titles of actions are capitalized: Ask For Input
    • Reference “the Ask For Input action” the first time, then drop “the” and “action” in subsequent uses.
  • It’s “shortcuts in the Shortcuts app”
  • “Siri Shortcuts” can refer to shortcuts, actions from third-party apps, and Siri-based shortcuts; I tend to save it for shortcuts activated via voice, however
  • Use “the My Shortcuts tab in Shortcuts”
  • The progession is “My Shortcuts” > “Shortcut editor” > then “Detail screen” for settings
  • Actions are located in the “Actions pane”
  • Shortcut titles should be written as if asked to Siri wherever possible; shortcuts for the widget are the exception, to save visual space
  • Avoid using “&” in the titles of shortcuts to avoid URL-encoding issues
  • Avoid emoji in the titles of shortcuts; use color for visual identification

Apple-specific nouns

  • Use “Home screen”, not “Home Screen” or “Homescreen”
  • Use “Time tracking”, not “time-tracking”
  • Use “Full Screen mode”, not “Fullscreen”

Grammar preferences

  • Use the Oxford comma in lists to provide clarity, with occasional use of the & to link two adjacent concepts.
  • Use hyphens for words like end-of-day, dashes – (using option -) to separate a single clause at the end of a sentence, and use full em dashes—without spaces—to add appositives (a small section of extra information that is inserted into a sentence for clarification) or to separate thoughts at the end of a sentence, or emphasize a list at the beginning of one
  • API, URL, JSON, ID, QR, RSS, MD, DF, PiP are capitalized accordingly
  • Features like Reading List are titled cased
  • Do not hyperlink punctuation at the end of sentences
    “Get my shortcut”/”Get the shortcut here.”/”View and add the shortcut here.”/”Get the shortcut” button

Linked posts

  • Author, on their blog/site | writing for website
  • Read the post/article/full piece/story (and follow him/her/them on Twitter / his/her/their blog)
  • Note for end of linked posts: If you have a blog post about Shortcuts, always feel free to tweet me the link. I post some of them here and in my newsletter too.

WordPress

  • Tags are lowercase unless a named entity
  • Images come after action, so you always read what happens and then see it after (instead of not knowing what the image you are seeing is about).