Part of my longstanding project at WorkJam was to create a style guide that was specific to our product, our users and catered to our need. This includes voice and tone guidelines, specifics on grammar and mechanics, component guidelines, and word lists. You can explore some excerpts from that work below.
Spelling and conjugation
Here’s an expanding list of spellings and conjugations for words we use often. These are standardized specifically for the product.
- admin
- API
- auto-assign (noun, adjective), auto assign (verb)
- autocomplete (noun, adjective), auto complete (verb)
- deactivate (not “inactivate”)
- favorite (noun, adjective), favorited (adjective)
- add to favorites (not “favorite” as a verb)
- subcategory
- time clock
- time frame
- time off (noun and adjective), times off (plural noun)
- timecard (rather than “timesheet”)
- to do
- training (not “training material”)
- trainings (plural noun)
- unassign
- URL
- WiFi
- workforce
- WorkJam
- workplace
Order of actions in action menus
- View
- Share
- Edit
- Approve
- Reject
- Publish
- Assign
- Duplicate
- Use as template
- Force complete
- Reset*
- Archive*
- Remove*
- Delete*
Action pairs
This list pairs actions we use in direct relation to or opposite each other in the context of different features. Is an approval request rejected or denied? Is a report generated or created? This list should be used when you’re unsure which among semantically similar verbs to use in a given situation.
- Add or delete
- Accept or decline an offer; respond to
- Apply sorting
- Apply filters; reset or clear
- Approve or deny a request; respond to
- Approve or reject a task; respond to
- Approve or unapprove a timecard
- Submit, retract, or delete a request
- Retract an open request.
- Delete an approved request.
- Assign or unassign a task, shift, survey, or training
- Generate, view, or download a report
Comment, feedback, & note
Comment, feedback, and note are all used as labels for similar text fields in WorkJam. This section covers the best time to use each label.
Comments are used mainly within Channels. Since channel discussions go in many directions, ‘Comment’ is an appropriately indistinct label for the text area. Plus, it is the industry-standard label.
N.B. Although a reply to a comment uses ‘reply’ as the action, a reply is still treated as a comment.
Feedback is used primarily in Tasks. For example, after a manager has reviewed a task, or after an auditor has completed an audit, a text area provides these users an opportunity to elaborate on what they have just gone over.
We use ‘Feedback’ in this case because we intend for users to be in a mindset of evaluating the work of others.
Notes are used primarily in Requests and Tasks. When a user makes or actions on a request, the text area gives them the opportunity to explain the request or action taken.
For example, “I have a regular appointment that day” is a note an employee might add to an availability request asking to be marked unavailable on Thursdays.
We use ‘Note’ because it conveys just that—like ‘memo’ but more localized to American English.
Conjunctions
Conjoin words when it makes the sentence easier to read and doesn’t detract from the overall meaning.
Much of this comes down to your sensitivity as a writer. “You're”, for example, is a natural conjunction. By contrast, “it’ll”, though shorter, might be a clunky and overly casual conjunction. Sometimes it’s better to keep two words unjoined to give a phrase more weight (“Do not” against “Don’t”).
Plurality
Should I parenthesize the 's'?
Defer to the plural form of a noun if there could be either one of it or many of them.
- Select target audiences ✅
- Select target audience(s) ❌
Table headers
To determine the plurality of a column or row header, evaluate whether a single cell under it is singular or plural.
Date and time
Date ranges and time frames
Hyphenate (en dash) date ranges and time frames.- Wednesday, September 1–Friday, September 3
- March 5, 2021–March 19, 2021
- 1:30 PM–1:45 PM
Date ranges with no ending
Add ‘onwards’ to the end of the start date. This is used for scheduling requests where the start date can begin in the future.
- September 16 onwards
End vs. due
For end users, use “Due:” to show the end point for assignments that can be completed early or late, like tasks, trainings, and surveys. Use “Ends:” for events.
When configuring date and time, the field labels for date ranges and time frames should always be “Start date” and “End date”.
Formatting date and time
Write out the full date whenever possible, omitting the current year. If there isn’t a lot of room, you can abbreviate the date.
- Wednesday, April 27, 1994
- April 27
- Sun, Jan 1
Write time of day in 12-hour format, capitalizing AM and PM.
- 3:45 PM
- Sun, Jan 1, 2032, 3:45 PM
Write out the full duration whenever possible, abbreviating if there are space constraints.
- 1 hour 12 minutes
- 1h 12m
Relative time
When it’s easier to interpret than the objective time, consider using time relative to the current time.
We show up to six days out relative to the due dates of trainings and surveys. Tasks should always show objective time. For project dates in Ops planner, we show both objective and relative time.
- Viewed: 5 minutes ago
- Due: In 3 days
- Due: Today
- Due: Yesterday
- Due: 3 days ago
- Friday, April 24 (2 days early)
Numbers
Ranges
Hyphenate (en dash) ranges of numbers.
- 1–100
Numbers less than 10
Spell out numbers one to nine in descriptions and for static strings.
- One, five, nine, 10, 11, 12
- You can create up to two labels
Exceptions
- Use digits when numbers are part of a range
- Use digits when the numbers are part of a dynamic string
- Use digits when representing a user-input value
- Enter a value greater than 1.
Overflow
When a count is so large it would either affect load time or exceed what we can show in a small container, cap the insignificant figures as 0’s rather than 9's.
- 10,000+ tasks ✅
- 900+ trainings ✅
- 999+ tasks ❌