Skip to content

A style guide on the standard format, spelling, and construction of commonly used words and phrases. For clarity and consistency of our internal and external communications – from our user interface to our sales, marketing, and commercial docs.

License

Notifications You must be signed in to change notification settings

trungvose/front-end-editorial-style-guide

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

13 Commits
 
 
 
 
 
 

Repository files navigation

Front End Editorial Style Guide

A style guide on the standard format, spelling, and construction of commonly used words and phrases.

For clarity and consistency of our internal and external communications – from our user interface to our sales, marketing, and commercial docs.

This is our practical guide at Zyllem. Therefore, many of these standards are related to the logistic sector.

Table of Contents

Capitalization

Case Use In Examples Rules
Title Case
  • Column Names (in tables)
  • Tab Names
  • Button Names
  • Menu Items
  • Clickable Elements (except if it is part of a sentence or error message)
  1. Do capitalize major words
    (e.g., Digitize Your Logistics)
  2. Do capitalize first and last word
    (e.g., Ordered On)
  3. Do not capitalize minor words except if #2 is true
    (e.g., Ordered on Network)
Sentence case
  • Check boxes
  • Radio buttons
  • Text box / field labels
  • Dialogs and instructions
  • Descriptions
  • Notifications 
  1. Do capitalize the first word only except if #2 is true.
  2. Do capitalize proper nouns (names of people, technology, etc.)
ALL CAPS
  • SECTION HEADERS

⬆ back to top

Message Templates (Common Errors, Confirmations, etc.)

Standard templates for some common messages

Case Template Example
Forms: Field is blank
  • FieldName is required.
  • Phone number is required.
  • Email address is required.
Forms: Wrong text format / value
  • Please enter the FieldName in format: XXX.
  • Please enter a valid FieldName.
  • Please enter a unique FieldName.
  • Please enter the email address in format: your@email.com
  • Please enter a valid Postal code.
  • Please enter a unique Code.
Forms: Wrong numeric format / value
  • Please enter a value between X and Y.
  • Please enter a <adjective(s)> number.
  • Please enter a value between 0 and 100.
  • Please enter a value less than or equal to 100
  • Please enter a value greater than or equal to 100
  • Please enter a positive whole number.
  • Please enter a unique number.
Error messages and warnings Message must contain at least 2 of the following in order:
  1. Problem
  2. Cause/Effect of problem
  3. Solution (with link if applicable)
  • Unable delete Warehouse1 because it is used by another resource.
  • ‘Operator1’ does not have a team with a ‘Driver’ role. This will result in Sync Issues. Please create or edit a team.
Action completed
  • The X has been <action in past tense>.
  • The team has been added.
  • The contact has been updated.
Confirm user-defined action
  • Are you sure you want to X? This action cannot be undone.
  • Are you sure you want to Cancel? This action cannot be undone.
Confirm deletion
  • Are you sure you want to delete X? This cannot cannot be undone.
  • Are you sure you want to delete Driver 1? This action cannot be undone.
Value already exists
  • 'XXX' already exists. Please enter a unique <PropertyName>.
  • 'CUSTOMER_SURVEY' already exists. Please enter a unique code name.
  • 'TEMP_ID' already exists. Please enter a unique ID.
An element has been updated/deleted
  • This <element> has been updated or no longer exists.
  • This phone number has been updated or no longer exists.
  • This email has been updated or no longer exists.
Attempting to delete a primary element
  • You cannot delete <a primary resource>.
  • You cannot delete a primary email.
  • You cannot delete a primary phone number.

Action no longer valid
  • This action is no longer valid to X/Y items. Please refresh the page and try again.
  • This action is no longer valid to 20/100 items. Please refresh the page and try again.
Missing configuration
  • There are no X defined on this X.
  • This feature requires a X. Please add a X.
  • X is not enabled in your portal. Please <instructions to solution>.
  • There are no users defined on this network.
  • This feature requires an operator. Please add an operator.
  • Support is not enabled in your portal. Please contact your administrator.
Pre-requisite configuration
  • This feature requires XXX. Please do this setting and try again.
  • This feature requires a default currency. Please set your currency and try again.
  • We noticed your file contains COD data. This feature requires a default currency. Please set your currency and try again.

⬆ back to top

Common Word Spellings

The spellings are based on:

  1. Most widely used spelling - references Google Ngram (books), Thesaurus and Dictionary.
  2. Avoid two words - combine words as first rule (e.g., geolocation). Otherwise, use dash if it makes more sense (e.g., cloud-based). This is a wide practice especially in the tech world.
  3. Your own terminology - for words that are not in any official guide or publication, you should create our own standard. Note that others may spell them differently and that's okay. Consistency is the key.
Use This Not This Comments
geofencing geo fencing, geo-fencing most compound words that start with geo are combined without a dash
geolocation geo location, geo-location, geo position
geozone

photosign / photosignature

photoSign, photo-sign, photo sign
reroute re-route, re route most words with the prefix re are combined without a dash
recalculate re-calculate
redeliver re-deliver
reassign, reassignment re-assign, re-assignment
reoptimize re-optimize
mutilingual most words with the prefix multi are combined without a dash
multicountry
multi-delivery
timestamp time stamp
cloud-based most compound words with the suffix based are combined with a dash
role-based
transaction-based
auto-assign, auto-assignment auto assign, autoassignment
autobundling, autobundle auto-bundling, auto-bundle, auto bundle
on-premise
cross-border
in-app inapp
real-time realtime
synchronize synchronise
sync, synced, syncs synch, synched, synchs

(This is not an American vs British spelling thing).

Although the past tense synched is more widely used than synced, the present tenses: sync and syncs are more widely used especially in computing (and the usage gap is so much wider). So for consistency and to save space, we will get rid of the "h".

endpoint end-point
email e-mail
SMS sms
Google Maps Google maps, google maps
iOS IOS, ios
Android android

⬆ back to top

Spelling and Formatting Rule

Spelling

Use This Not This Comment
Use American English instead of British English (e.g., customize, fulfill) customise, artefacts, fulfil, synced We go for what is more widely used worldwide. See this example

Numbers

Use this

  • Spell out if it's less than 10, use numeric if it's more than 10 (e.g., three, 25)
  • Spell out when used as a compound adjective (fifty-thousand-foot view)

Not this

3 layers, twenty-five drivers

50-thousand-foot view

Date and time

Use this

  • Date
  • Time
  • Date and time

Not this

  • date
  • time
  • Date and Time

Units of measurement

These abbreviations must be used in both plural and singular forms.

For consistency and due to space constraints in the mobile app, let's NOT put a space between the number and the unit.

Time

Use This Not This
Days, hours, minutes, seconds: d, h, min, s (e.g., 4d, 2h, 8min, 5s) 4 d, 2 h, 8 min, 5 s
6AM, 3PM 6am, 6Am, 3Pm, 3pm

Distance

Use This Not This
Kilometers, meter: km, m (e.g., 34km, 500m) 34 km, 500 m

Commas

Use This Not This Comment
Use serial comma (e.g., distance, traffic, and capacity). Notice the comma after "traffic". Enterprise, network and operator A must in contracts and legal documents. Here's one of the many reasons

⬆ back to top

Common Grammar Dilemmas

1. Plural Mishaps

Use this Not this
Driver Name Drivers Name
Customer Survey Customers Survey
Item Summary Items Summary

2. "&" versus "And"

& = united And = separated
Search & select
Both actions were performed as one like when you use a barcode scanner to scan barcode and the item was selected automatically
Search and select
Search for the item and then tap to select the check box
Cookies & Cream
Cookie & Cream
Cookies and Cream
Cookie and Cream
Fruit & Nut
Fruit & Nut
Fruit and Nut
Fruit & Nut

3. One word versus two words

One word = noun Two words = verb
What is your login password? Log in with your account
The pickup time is at 3PM Pick up the parcel

⬆ back to top

Contributing

I know this collection of standards is not perfect and still needs to improve. If you have any ideas, just open an issue and tell me what you think.

If you'd like to contribute, please fork the repository and make changes as you'd like. Pull requests are warmly welcome.

About

A style guide on the standard format, spelling, and construction of commonly used words and phrases. For clarity and consistency of our internal and external communications – from our user interface to our sales, marketing, and commercial docs.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published