Adhering to certain rules of grammar and mechanics helps us keep our writing clear and consistent. This section will lay out our house style, which applies to all of our content unless otherwise noted in this guide.
Write for all readers. Some people will read every word you write. Others will just skim. Help everyone read better by grouping related ideas together and using descriptive headers and subheaders.
Focus your message. Create a hierarchy of information. Lead with the main point or the most important content, in sentences, paragraphs, sections, and pages.
Be concise. Use short words and sentences. Avoid unnecessary modifiers.
Be specific. Avoid vague language. Cut the fluff.
Be consistent. Stick to the copy patterns and style points outlined in this guide.
Abbreviations and acronyms
If there’s a chance your reader won’t recognize an abbreviation or acronym, spell it out the first time you mention it. Then use the short version for all other references. If the abbreviation isn’t clearly related to the full version, specify in parentheses.
- First use: Network Operations Center
- Second use: NOC
- First use: Coordinated Universal Time (UTC)
- Second use: UTC
If the abbreviation or acronym is well known, like API or HTML, use it instead (and don’t worry about spelling it out).
Use active voice. Avoid passive voice.
In active voice, the subject of the sentence does the action. In passive voice, the subject of the sentence has the action done to it.
- Yes: Marti logged into the account.
- No: The account was logged into by Marti.
Words like “was” and “by” may indicate that you’re writing in passive voice. Scan for these words and rework sentences where they appear.
One exception is when you want to specifically emphasize the action over the subject. In some cases, this is fine.
- Your account was flagged by our abuse team.
There are two forms of capitalization. We don’t use title case (capitalization of the first letter of every word except articles, prepositions, and conjunctions). We use sentence case (capitalization of the first letter of the first word).
When writing out an email address or website URL, use all lowercase.
Don't capitalize random words in the middle of sentences. Here are some words that we never capitalize in a sentence. For more, see the Word List.
Emoji are a fun way to add humor and visual interest to your writing, but use them infrequently and deliberately.
Where we can use emoji:
- Facebook posts
- Instagram posts
Where we don’t use emoji:
- Marketing materials
Spell out a number when it begins a sentence. Otherwise, use the numeral. This includes ordinals, too.
- Ten new employees started on Monday, and 12 start next week.
- I ate 3 donuts at Coffee Hour.
- Meg won 1st place in last year’s Walktober contest.
- We hosted a group of 8th graders who are learning to code.
Numbers over three digits get commas:
Write out big numbers in full. Abbreviate them if there are space restraints, as in a tweet or a chart: 1k, 150k.
Spell out the day of the week and abbreviate the month, unless you’re just referring to the month or the month and the year.
- Saturday, Jan. 24
- Saturday, Jan. 24, 2015
- January 2015
Decimals and fractions
Spell out fractions.
- Yes: two-thirds
- No: 2/3
Use decimal points when a number can’t be easily written out as a fraction, like 1.375 or 47.2.
Ranges and spans
Use a hyphen (-) to indicate a range or span of numbers.
- It takes 20-30 days.
When writing about US currency, use the dollar sign before the amount. Include a decimal and number of cents if more than 0.
When writing about other currencies, follow the same symbol-amount format:
Use periods without spaces between numbers (no parentheses or dashes). Use a country code if your reader is in another country.
Use numerals and am or pm without a space. Don’t use minutes for on-the-hour time.
Use a hyphen between times to indicate a time period.
The apostrophe’s most common use is making a word possessive. If the word already ends in an s and it’s singular, you also add an ‘s. If the word ends in an s and is plural, just add an apostrophe.
- The donut thief ate Sam’s donut.
- The donut thief ate Chris’s donut.
- The donut thief ate the managers’ donuts.
Apostrophes can also be used to denote that you’ve dropped some letters from a word, usually for humor or emphasis. This is fine, but do it sparingly.
Use a colon (rather than an ellipses, em dash, or comma) to offset a list.
- Erin ordered three kinds of donuts: glazed, chocolate, and pumpkin.
You can also use a colon to join two related phrases. If a complete sentence follows the colon, capitalize the first word.
- I was faced with a dilemma: I wanted a donut, but I’d just eaten a bagel.
When writing a list, use the serial comma (also known as the Oxford comma).
- Yes: David admires his parents, Oprah, and Justin Timberlake.
- No: David admires his parents, Oprah and Justin Timberlake.
Otherwise, use common sense. If you’re unsure, read the sentence out loud. Where you find yourself taking a breath, use a comma.
Dashes and hyphens
Use a hyphen (-) without spaces on either side to link words into single phrase, or to indicate a span or range.
- first-time user
Use an em dash (—) without spaces on either side to offset an aside.
Use a true em dash, not hyphens (- or --).
- Multivariate testing—just one of our new Pro features—can help you grow your business.
- Austin thought Brad was the donut thief, but he was wrong—it was Lain.
Ellipses (...) can be used to indicate that you’re trailing off before the end of a thought. Use them sparingly. Don’t use them for emphasis or drama, and don’t use them in titles or headers.
- “Where did all those donuts go?” Christy asked. Lain said, “I don't know...”
Ellipses, in brackets, can also be used to show that you're omitting words in a quote.
- “When in the Course of human events it becomes necessary for one people to dissolve the political bands which have connected them with another and to assume among the powers of the earth, [...] a decent respect to the opinions of mankind requires that they should declare the causes which impel them to the separation.”
Periods go inside quotation marks. They go outside parentheses when the parenthetical is part of a larger sentence, and inside parentheses when the parenthetical stands alone.
- Christy said, “I ate a donut.”
- I ate a donut (and I ate a bagel, too).
- I ate a donut and a bagel. (The donut was Sam’s.)
Question marks go inside quotation marks if they’re part of the quote. Like periods, they go outside parentheses when the parenthetical is part of a larger sentence, and inside parentheses when the parenthetical stands alone.
Use exclamation points sparingly, and never more than one at a time. They’re like high-fives: A well-timed one is great, but too many can be annoying.
Exclamation points go inside quotation marks. Like periods and question marks, they go outside parentheses when the parenthetical is part of a larger sentence, and inside parentheses when the parenthetical stands alone.
Never use exclamation points in failure messages or alerts. When in doubt, avoid!
Use quotes to refer to words and letters, titles of short works (like articles and poems), and direct quotations.
Periods and commas go within quotation marks. Question marks within quotes follow logic—if the question mark is part of the quotation, it goes within. If you’re asking a question that ends with a quote, it goes outside the quote.
Use single quotation marks for quotes within quotes.
- Who was it that said, “A fool and his donut are easily parted”?
- Brad said, “A wise man once told me, ‘A fool and his donut are easily parted.’”
Go easy on semicolons. They usually support long, complicated sentences that could easily be simplified. Try an em dash (—) instead, or simply start a new sentence.
Don't use ampersands unless one is part of a company or brand name.
- Ben and Dan
- Ben & Jerry’s
People, Places, and Things
When referring generally to a file extension type, use all uppercase without a period. Add a lowercase s to make plural.
When referring to a specific file, the filename should be lowercase:
If your subject’s gender is unknown or irrelevant, use “they,” “them,” and “their” as a singular pronoun. Use “he/him/his” and “she/her/her” pronouns as appropriate. Don’t use “one” as a pronoun.
For more on writing about gender, see Writing about people.
When quoting someone in a blog post or other publication, use the present tense.
- “As smartphone use in the workplace peaks, business leaders, through Eko, have an unprecedented opportunity to transform the way they communicate and collaborate with their colleagues,” says Chartsiri Sophonpanich.
Names and titles
The first time you mention a person in writing, refer to them by their first and last names. On all other mentions, refer to them by their first name.
Capitalize the names of teams, departments, and individual job titles.
The first time you mention a school, college, or university in a piece of writing, refer to it by its full official name. On all other mentions, use its more common abbreviation.
- Chulalongkorn University, CU or Chula
States, cities, and countries
Spell out all city and state names. Don’t abbreviate city names.
On first mention, write out United States. On subsequent mentions, US is fine. The same rule applies to any other country or federation with a common abbreviation (European Union, EU; United Kingdom, UK).
URLs and websites
Capitalize the names of websites and web publications. Don’t italicize.
Avoid spelling out URLs, but when you need to, leave off the http://www.
Writing about Eko
Our company's legal entity name is "Eko Corporation Co.,Ltd." Our trade name is "Eko Communications." Our product name is "Eko". Use "Eko Corporation Co.,Ltd." only when writing legal documents or contracts. Otherwise, use "Eko Communications." or "Eko."
Always capitalize the first “E” in Eko and both "E" and "C" in Eko Communications.
Refer to Eko as “we,” not “it.”
Capitalize the proper names of Eko products, features, pages, and tools. When referencing non-trademarked products like S and others, include "Eko" in the name on first mention.
- Eko Green
- Eko S
- Company Directory
Writing about other companies
Honor companies’ own names for themselves and their products. Go by what’s used on their official website.
Refer to a company or product as “it” (not “they”).
Slang and jargon
Write in plain English. If you need to use a technical term, briefly define it so everyone can understand.
- Collaborate on projects with your coworkers using Eko’s Workspaces, conversations organized by topic, so that it’s easier to keep track of multiple discussions.
Use italics to indicate the title of a long work (like a book, movie, or album) or to emphasize a word.
- Star Wars
- Brandon really loves Star Wars
Use italics when citing an example of an in-app Eko element, or referencing button and navigation labels in step-by-step instructions:
- When you're all done, click Send.
- The familiar A/B testing variables — Subject line, From name, and Send time — have now been joined by Content, and up to 3 combinations of a single variable can now be tested at once.
Don’t use underline formatting, and don’t use any combination of italic, bold, caps, and underline.
Left-align text, never center or right-aligned.
Leave one space between sentences, never two.
Use positive language rather than negative language. One way to detect negative language is to look for words like “can’t,” “don’t,” etc.
- Yes: To get a donut, stand in line.
- No: You can’t get a donut if you don’t stand in line.