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
• Message Templates (Common Errors, Confirmations, etc.)
• Common Word Spellings
• Spelling and Formatting Rule
  • Spelling
  • Numbers
  • Date and time
  • Units of measurement
    • Time
    • Distance
  • Commas
• Common Grammar Dilemmas
  • 1. Plural Mishaps
  • 2. "&" versus "And"
  • 3. One word versus two words
• Contributing

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)		Do capitalize major words (e.g., Digitize Your Logistics) Do capitalize first and last word (e.g., Ordered On) 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		Do capitalize the first word only except if #2 is true. 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: Problem Cause/Effect of problem 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	Cookies and Cream
Fruit & Nut	Fruit and 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.