Meltano Style Guide

This style guide is designed to address common writing issues and questions, and to provide tips to help us standardize and improve our messaging documents. It also provides specific guidance regarding Meltano’s brand, tone, and voice. For a general overview of the company’s brand personality (including Melty the Dragon), tone of voice, brand resources, and logos and artwork, consult the Meltano Brand Kit.

As Meltano’s voice and tone further develops over time, here are some helpful resources and guidelines.

## Helpful resources

General tone-of-voice writing guidelines:

Things to do:

Think “business casual”: well put together, neat, and crisp, but not stiff or formal.
Use contractions to make your writing more natural and accessible to readers.
Use a conversational tone and personalize whenever possible with “you” instead of “user” or “developer,” etc.
Use active (as opposed to passive) voice: Note that you’ll often find words such as “was,” “were,” “by,” “has,” and “have” in passive sentence constructions. (See examples below.)
Pair text with images or videos to ensure accessibility and clarity.
Use examples when possible.
Highlight community wins and individuals.

NOTE: Once in a while, passive voice comes in handy when you want to communicate something in an indirect way. (Politicians often use passive voice to avoid taking responsibility. Example: Mistakes were made, and due diligence was not performed.”)

Things to avoid and other guidance:

Be careful about using slang, which may not translate into other languages or may, in some cases, come across as unprofessional. (It depends on the delivery vehicle and the audience. For instance, you would write in a more casual tone in a blog than you would in a white paper.)
Swearing.
Cliches and marketing jargon: What do you think about when you hear terms such as “best-of-breed,” “guru,” “growth hacking,” “holistic,” or “state-of-the-art,” and “synergy,” just to name a few cringe-worthy, overused marketing terms? Check out The Cringiest and Most Overused Words in Marketing for more terms to use sparingly, only with qualification, or never.
Being flippant about sensitive topics.
Overselling or overpromising.

Anthropomorphisms (attributing human characteristics to an object). Also, don’t ascribe feelings to a company.

Correct	Incorrect
The company realized it was time to rebrand.	The company felt it was time to rebrand.

You can use the plural form for Meltano (Example: “Meltano’s open-source community), but avoid pluralizing the company’s products.

Correct	Incorrect
The Meltano DataOps Platform Infrastructure	Meltano’s DataOps Platform Infrastructure

Sentences and paragraphs: As a general guideline, try to keep sentences to 25-to-30 words and paragraphs to three-to-four sentences. Use bullets to break up long blocks of text.
Use gender and power-neutral language. |Gender noun/pronoun| Alternative | |——–|–| | Man | Person, individual | | Mankind | People, human beings, or humankind | | Layman | Layperson or average person | | Manmade | Machine-made, handmade | | Man-hours | Manual hours or staff hours | | Manpower | Labor | | Common man | Common person |
Follow individual guidance for personal pronouns:
1. She/her
2. He/him
3. They/them
Don’t use words that express archaic power dynamics:

Correct	Incorrect
The master spreadsheet	The main spreadsheet

Cut or revise run-on sentences: Vary your sentence lengths, but in general, aim for sentences that are 25-to-30 words or less. As workarounds for a long sentence, you can divide it into two sentences or insert a semicolon between its two clauses.
Avoid wordiness.

Word or phrase	Substitute
Is able to	Can
Utilize, utilization	Use
Eventuality	If
Necessitate	Need
Consequently	So
Modification	Change
Expenditure	Cost, expense
A number of	Numerous or several
A variety of	Various
Additionally, the company also …	Use either additionally or also, but not both
Chose to, or decided to implement/install	Implemented or installed
Due to the fact that…	Because
Each individual	Each
In order to	To
In regard to	Regarding
Made the decision to	Decided to
Prior to	Before
Phrasal verbs (a verb and a preposition): call up, click on, free up, print out, user	Call, click, free, print, user
“Through the elimination of,” “through the use of,” etc.	“By eliminating” and “by using”
Was able to create	Created

Avoid exaggerations or claims for which you have no objective, third-party proof.

Avoid making hyperbolic claims and using over-the-top adjectives only hurts the brand because they’re neither accurate nor provable. A good general rule of thumb is to follow this guideline, the bedrock upon which most legal guidelines for marketing are based: If you can (objectively) prove it, you can claim it.

Examples of words to avoid unless you can definitively prove them (and alternatives)

Instead of:	Use:
The biggest, best, fastest, greatest …	One of the biggest, best, fastest, greatest …
Unmatched	Superior
Unprecedented	Uncommon or distinctive
Unsurpassed	Exceptional

NOTE: You can “soften” a claim with phrases such as “can” or “help,” or “is designed to.” (Example: “Product X helps you,” or “Product X can,” or “Product X is designed to …)

Acronyms:

Spell out at first occurrence in text (not title or subhead), then use abbreviated versions thereafter.

Correct	Incorrect:
Extract, load, transfer (ELT) (The next time you use the term ELT in the text, you can use ELT.)	ELT (at first occurrence)
continuous integration and continuous delivery\ (CICD)\ Or deployment	CICD (continuous integration and continuous delivery*)

Blog titles and subheads: Keep as concise and benefit-driven as possible, and don’t add exclamation marks. Also, use serial caps for titles and subheads.

Bulleted lists:

Bullets help you:

Organize complicated information
Promote readability by providing white space
Draw the reader’s eye

That said, reading long lists of items can be tedious, so try to keep lists to ten items or less.

Use dark, round bullets for main text; use clear, round bullets for sub bullets (except in blogs, where the bullet style is templatized).

Example:
- Item A
- Sub bullet A
- Item B
Introduce bullets using a colon (:) after the introductory phrase.
Capitalize the first letter of the first word in each bullet.
Use only one carriage return before and after each bullet.
If any item in the bulleted list is a complete sentence or contains a complete sentence, put a period at the end of all items.

Example:

You can reach me in one of three ways:
- You can email me.
- You can text me.
- You can call me.
If none of the bullets form a complete sentence, don’t use any periods in the list.

Example:

You can reach me in three ways:
- Email
- Text
- Phone
Make your bullets parallel. For instance, you could start all bullets with nouns or verbs. (In general, use verbs when possible because they are “action” words.) Example of bullets that start with a verb:

Product helps you:
- Save time
- Optimize resources
- Implement best-practice guidelines
Examples of starting a list with a noun:

We are facing several critical challenges, a few of which include:
- Inflation
- Climate change
- Food and water shortages

Citations and footnotes:

Follow these guidelines about how and when to cite information from third-party sources. While you don’t need to cite basic information that’s commonly known, it’s best to err on the side of caution if you’re unsure.

Cite information (with a footnote and quotes) you take directly from a source, which will usually be another company’s website.
Use sequential numbers to cite sources, even if you’re repeatedly citing the same source.
Footnote numbers are usually placed at the end of the relevant clause or sentence (after the period, and in uppercase script).
Fully source footnotes at the end of your document, or at the bottom of the page on which it appear

Example of a citation: According to CarLogos.org, “Volkswagen, Toyota, and Daimler are the three leading passenger car manufacturers in the world.”1

Example at bottom of page or end of document:

1 [author name, if available], CarLogos.org, The Largest Car Companies in the World (New), February 21, 2022, https://www.carlogos.org/reviews/largest-car-companies.html

For more information about citing and footnoting various sources, check out: [https://www.easybib.com/guides/citation-guides/chicago-turabian/footnotes/](https://www.easybib.com/guides/citation-guides/chicago-turabian/footnotes/

Customer quotes:

The most important thing to remember is to make sure you have (written) permission to quote customers, unless you “blind” them.

Correct for quotes you have direct permission to make public:

“Meltano is our go-to DataOps solution.”

—Janet Smith, CEO, Company X

Incorrect for quotes you have direct permission to make public:

Meltano is our go-to DataOps solution.

-Janet Smith, Company X, CEO

Correct for “blind” quotes:

“Meltano is our go-to DataOps solution.”

—CEO of a leading European retailer

Incorrect for “blind” quotes:

Meltano is our go-to DataOps solution.

CEO of Company X

NOTE: A general best-practice guideline for customer quotes is to keep them under 300 characters (with spaces).

Date ranges:

To express a range of dates, use the words “from” and “through.” Don’t use “to” and “between.”

Correct	Incorrect
From 2019 through 2021	Between 2019 and 2021
From May through August 2022	May - August 2022
From June 2019 through January 2022	Between June 2019 and January 2022

Email subject lines and banners:

Avoid spam filters by keeping subject lines to less than 70 characters and not using exclamation points in subject lines or banners.

Numbers

Spell out numbers one through ten, and use numerical representatives for 11 and up.
Use colons and numbers to indicate ratios.

Correct	Incorrect
I have eight things to do on my list.	I have 8 things to do on my list.
3:2	Three to two (or 3 to 2)

Exceptions: numbers associated with versions, currency, numbers identifying a project phase or installation level, when describing a series of elements or a range of numbers in which one of the numbers that occur near one another in the text

Correct	Incorrect
V6.0	Vsix.zero
Phase 1, Tier 1	Phase one, Tier one
You have 5 – 9 options.	You have 6 to 9 options.

Punctuation

Commas:

Use commas to	Example
Join two complete sentences	Today is my sister’s birthday, so I’m taking the day off to take her out to lunch.
Separate introductory clauses	While you were working to meet your deadline, I went to the deli to pick up lunch for you.
Separate words	However, my order wasn’t ready on time.
Parenthetical information	I told the deli to add tomatoes, which are part of the nightshade family, to your sandwich.
Explain a noun	Taylor, a data professional at Meltano, lives in Texas.
Separate dates, addresses, and geo locations	The last time I went to an art fair was on May 23, 2021, in Atlanta, Georgia.
Separate adjectives that modify the same noun (where you could also use the word “and”)	It was a dark, stormy night.
Avoid confusion with a concluding conjunction	Correct: I had broccoli, carrots, and black beans and rice for dinner.
Separate elements in a series	Correct: ELT stands for extract, load, and transfer

Dashes: Dashes are often a stand-in for commas. They also come in handy when you want to break up your text. Use them sparingly, and when you do, use em (long) dashes rather than short (en) dashes, with no spaces on either side.

Correct	Incorrect
Want to work for a rapidly growing startup that’s changing the DataOps landscape — with some great perks?	Want to work for a rapidly growing startup that’s changing the DataOps landscape–with some great perks?

Hyphens: When in doubt, consult Merriam Webster.

What and When to Hyphenate	What and When to (Usually) Not Hyphenate	Example
Compound adjectives	When connecting a prefix to a suffix, as with antivirus, multichannel, and worldwide, unless doing so avoids confusion or ambiguity, as in multi-core processors.	World-class provider, step-by-step guide, best-practices-based software, cost-effective solution
Terms such as “real time” and “decision making” are only hyphenated when they’re used as adjectives		real-time notification, or decision-making processes
When expressing fractions		Correct: two-thirds
When identical letters are involved		Correct: co-opt, de-emphasize

Periods: When quoting text, place periods inside quote marks. Use one space between the period and the beginning of the next sentence.
Colons and semicolons:
- Use a colon to list items after an introductory phrase. - Example: Here’s what you get when you sign up for our service: value, time savings, and consistently high performance.
- Use a semicolon in place of a comma or to join two related clauses.
  - Exmaple, In place of a comma: Catherine was so busy at work that she skipped lunch, breaks, and tea time; nor did she take her dog for a walk.
  - Example, To join two related clauses: John worked all night to finish coding; nevertheless, he didn’t finish writing the program.
Ellipses: An ellipsis consists of three dots (…). You can use it to omit words, sentences, or sections, or to indicate hesitation. It can also represent a trailing thought, in which case it typically comes at the end of a sentence. If you use an ellipsis in the middle of a sentence, use a space before and a space after. If you use it at the end of a sentence, don’t add a period.
- Example: I didn’t know you were feeling so … frustrated.
- Example: I didn’t know you felt so frustrated … Was it something I said?

Quotation marks: Use double (“), not single (‘), quotation marks when needed. Use curly (“smart”), not straight, quotation marks and apostrophes in all documents.

NOTE: Remember that periods and commas go inside quotes, but colons and semicolons go outside.
- Example: Taylor said, “Periods go inside quotes.”
- Example: Did she keep the document “as is,” or did she change it?
- Example: I think she kept the document “as is”; I’ll check it to make sure.
Parentheses: When not used to indicate abbreviations or to enclose numbers in a list, parentheses usually serve to:
- Enclose additional information
  - Example: The CEO told us (what great news!) to take Monday off.
- Substitute for the word “or”
  - Example: What part(s) do I need to fix my car?
Apostrophes: Use to indicate possessive or plural possessive case and for contractions. This website is a great resource for learning more about plural possessive nouns.

Examples
Possessive nouns reflect ownership: Pat’s computer or Taylor’s meeting
Plural possessive nouns indicate ownership by more than one: I had to take my dogs’ to the vet. (There is more than one dog.) If a plural possessive noun ends in “s,” insert the apostrophe after the “s” to indicate more than one: the dogs’ vet visit.
Contractions remove a word: It’s going to rain today. (You could substitute “It is.”) But remember that possessive pronouns don’t require a contraction: The cat licked its paws.
Exception: For ages and decades, don’t use apostrophes: He’s in his 30s. (Or: For some of us, the 1990s were a lost decade.)

Translation and currency: If you’re writing for a global audience, remember that most symbols don’t translate. Spell out symbols such as $, %, &, +, =, #, /

Correct:	Incorrect:
Correct: USD 1.5 billion	Incorrect: $1.5B
Correct: fifteen percent	Incorrect: 15%, fifteen percent
Correct: Are you and Taylor meeting today?	Incorrect: Are you & Taylor meeting today?
Correct: Five plus five equals ten. (Or 5 plus 5 equals 10.)	Incorrect: Five + five = ten.
Correct: You are #3 in the queue.	Incorrect: You are number three in the queue.
Correct: Choose “or” or “and”.	Incorrect: I have an idea where you and/or your friends can go for dinner.

NOTE: For terms that require slashes, such as input and output (I/O), spell it out at first

occurrence (input and output) and then subsequently use the slash when you refer to I/O.

Time: Use Coordinated Universal Time (UTC)
Unclear antecedents: When a sentence doesn’t clearly identify which noun a subsequent pronoun refers to, you have an unclear antecedent. Sentences that contain unclear antecedents often start with “It,” “this,” or “that.”

NOTE: Sometimes it’s okay to start a sentence with these words; just make sure its antecedent (the noun or concept it’s referring to) is clear.

Correct	Incorrect
My laptop, which was in my car, disappeared.	My laptop was in my car, but it disappeared.
The company advertised on a billboard for the first time. This medium will attract new customers.	The company advertised on a billboard for the first time. This will attract new customers.
It annoyed me that she didn’t apologize for being late to our meeting.	She was late to our meeting and offered no apology, which annoyed me.

How to talk about the Meltano Product Family and Team:

We have three main “product lines.” Each one should be referenced in speech and in writing in specific ways.

Meltano Product Family

|Correct| Incorrect | |——–|–| | Meltano |The Meltano | | The Meltano SDK, the Meltano Tap SDK, or the Meltano SDK for Singer Taps After the Meltano-specific name has been been referenced, these are okay: the SDK, the Tap SDK, the SDK for Taps, the SDK for Singer Taps, the Taps SDK by Meltano) | Singer SDK, Singer SDK for Taps, Singer-sdk, Meltano’s Singer SDK, Singer SDK by Meltano | | MeltanoHub, Meltano Hub for Singer, the Hub | The MeltanoHub, The SingerHub, The Nub for Singer |

The Meltano team

Trademark language:

Meltano is a registered trademark in the USA and China. (Further details, such as the registration number and certificate, can be found in the “Meltano” 1Password vault.)

Edit this page!