Grammar & Mechanics

We use these grammar conventions to make our language clear and consistent.

Abbreviations

The first time you use an abbreviation, spell it out, and then refer to it by initials in parentheses. For example: Software Bill of Materials (SBOM). Don’t use an abbreviation if you’re not going to use it again later in the text. If the abbreviation or acronym is well known to your audience, like PDF or HTML, use it instead (and don’t worry about spelling it out).

• First use: Software Development Life Cycle (SDLC)
• Second use: SDLC
• First use: Infrastructure as Code (IaC)
• Second use: IaC

Don’t use full stops (periods) in abbreviations.

• YES: RSVP
• NO: R.S.V.P.

When pluralizing abbreviations and acronyms, use a lowercase “s” and do not insert an apostrophe.

• YES: Download the PDFs 
• NO: Download the PDF’s

Be careful when referring to “open source software.” 

Capitalization

Capitalize something if it meets one or more of these criteria:

• It’s the first word in a sentence, quoted sentence, or bullet point
• It’s a proper noun (including brand names, product names)
• It’s a title of any kind: like blog posts, web pages, or presentation documents (use sentence case — see below)
• It’s a heading or subheading
• It’s the header cell in a table

Sentence Case

We use sentence case to capitalize the first letter of the first word for titles of:

• Published written content (whitepapers or other documents, reports, blog posts, articles, events)
• External presentations
• Video

Title Case

We use title case to capitalize the first letter of every word (except articles, prepositions, and conjunctions) for titles of:

• Products (Sonatype Lifecycle)
• Product add-ons (Advanced Legal Pack)
• Named product features (i.e. Release Integrity)
• Specific components (Struts)

Specific Uses

Emails and Websites

When writing out an email address or website URL, use all lowercase.

• YES: Please email info@sonatype.com to learn more.
• YES: Please visit sonatype.com to learn more.

Job Titles

Capitalize specific job titles, but not generic. 

• YES: Brittany is one of our finest engineers.
• YES: Brittany, a Senior Software Engineer, has proved to be a valuable asset.

Product Names

Sonatype product names (including developer tools like Chelsea and Nancy) are considered to be proper nouns, and should be capitalized.

• YES: She uses Repository Firewall to protect her Nexus Repository every day.

Product Features

Named Sonatype product features are also capitalized. 

• YES: He loves the Release Integrity feature in the Advanced Developer Pack.

Events

Capitalize specific events, but not generic.

• YES: RSVP now for the DevSecOps Leadership Forum.
• NO: The Forum is being held in Dallas.

Published Content

Capitalize specific pieces, but not generic.

• YES: The new report is available for download.
• YES: I just downloaded the 10th Annual State of the Software Supply Chain Report.

Content Headlines

Use title case for main headlines/titles of pages/reports/whitepapers.

Content Subheads

Choose one of the following formats in a single page or document and be consistent.

• If your page's subheads are brief and not a complete sentence, use title case. Example here.
• If your page's subheads are complete statements written as a full sentence use sentence case (only capitalize the first letter of the first word and any proper nouns). Example here.

Random Words

Don't capitalize random words in the middle of sentences. Here are some words that we never capitalize in a sentence.

• website
• internet
• online
• email
• open source

Other Brands or Products

Ensure use of capitalization is consistent with the market’s use. For example:

• npm, not NPM
• NuGet, not nuget
• PyPI, not pypi

Citations

When to Use Italics: Titles of Larger Works

Italics indicate the title of a major or larger work. The title of any piece that stands alone as a single, unified work should be italicized. Use italics for:

• Books
• Magazines
• Journals and newspapers
• Collections and anthologies
• CDs and albums
• Ballets, operas, and plays
• Television series
• Movies/films
• Video games
• Websites
• Work of art/art exhibits

When to Use Quotation Marks: Titles of Smaller Works

Since quotation marks are tiny, you can remember that they are used for smaller works within a larger work or collection. Use quotation marks for:

• Poems
• Short stories
• Book chapters
• Articles in journals, magazines, newspapers, and websites
• Songs
• Single television episodes

When to Use Underlining: Don't (for Citations)

Underlining for citations was meant to replace italics in handwritten documents (because who has mastered the art of writing in italics?).

So avoid underlining for citation purposes, use italics instead. This will avoid confusion around hyperlinks in digital text.

Lists

Use lists to draw the reader's eye and make items easier to scan and follow. Use proper punctuation in your items if they are complete sentences. Try to limit lists to 10 items or less. If you need more items, see if you can split the list into multiple lists.

Bulleted

Use bulleted lists for options, or a list where the order of the items doesn't matter. If the bullets complete the introductory sentence, start the fragments with lowercase and end with a period.

YES:

Nexus Container allows you to:

• identify vulnerabilities and compliance issues before containers deploy.
• prevent cyber attacks with real-time visibility into network activity.
• save time on policy management. Our behavioral learning analyzes traffic then builds and enforces security policies for you.
• stay on one platform with our easy integration with Nexus Repository.

If the bullets are complete sentences themselves, use title case and end with a period. 

YES:

Key Benefits of Nexus Container

• Identify vulnerabilities and compliance issues before containers deploy.
• Prevent cyber attacks with real-time visibility into network activity.
• Save time on policy management. Our behavioral learning analyzes traffic then builds
  and enforces security policies for you.
• Stay on one platform with our easy integration with Nexus Repository.

If the listed items do not complete a sentence, or are not a complete sentence on their own, capitalize the first word, but do not use a period.

YES:

Nexus Container key features:

• Vulnerability and compliance issue identification
• Cyber attack prevention
• Traffic analysis and security policy enforcement informed by behavioral learning
• Easy integration with Nexus Repository

Phrase each item in a parallel way.

NO:

Key Benefits of Nexus Container

• Identify vulnerabilities and compliance issues before containers deploy.
• Cyber attack prevention
• Users save time on policy management. Our behavioral learning analyzes traffic then builds
  and enforces security policies for them.
• you can easily integrate with Nexus Repository

Numbered

Use numbered lists for tasks, or lists where the order of the items matters. Always capitalize the first word in each item and end the item with a period. You don't need to create a list for tasks that have two or fewer steps.

YES:

Get started in a few simple steps.

1. Fill out the form on this page.

2. Our team will grant you access and help you get set up.

3. Once you have access, check out our documentation for how to generate an access token.

4. Integrate Sonatype Lift into your pipelines and start remediating.

Numbers

Write the numbers one to ten:

• YES: Eight out of every ten employees work remotely. 
• NO: 8 out of every 10 employees work remotely. 

Use digits for anything higher:

• YES: The feud between the two developers over Star Wars vs. Star Trek has been going on for more than 23 years.
• NO: The feud between the two developers over Star Wars vs. Star Trek has been going on for more than twenty-three years.

Exceptions to this rule can be made for marketing or blog post titles and in graphic designs:

• OK: The Top 5 Software Vulnerabilities in the Financial Industry

For numerals over 999, insert a comma for clarity:

• YES: Over 9,000 people registered for All Day DevOps in 2019.

For ordinal numbers, spell out first to tenth. After that use 11th, 12th...

Dates

Whenever possible, spell out the day of the week and the month.* Always use all four digits for the year. Do not use ordinals in dates (21st, 32nd, etc.)

• YES: Monday, January 15
• NO: Mon., Jan. 15
• YES: Monday 15 January (international)
• NO: Monday 15th January

*Exceptions may be made when space is an issue.

To avoid confusion, always use the whole year, even when referring to a cultural time frame:

• YES: 2020
• YES: The 1920s
• NO: The ’20s

Money

When writing about US currency, use the dollar sign before the amount. Include a decimal and number of cents if more than 0.

• YES: $20
• YES: $19.99

When writing about other currencies, follow the same symbol-amount format.

• YES: ¥1
• YES: €1

Don’t use decimals unless cents are included.

• YES: The starter package is $120 per user per year.

Leave out decimal cents whenever possible.

• YES: $89,000
• NO: $89,000.00

In the rare occasion you need to refer to something that’s less than $1, write out “cents” in full or use a dollar sign with a zero before the decimal.

• YES: $1 of expansion ACV costs 57 cents to acquire.
• YES: $1 of expansion ACV costs $0.57 to acquire.
• NO: $1 of expansion ACV costs .57 to acquire.

For amounts of money later than $999,999.99, you should use the abbreviation (you may use if for amounts less than that as well). The abbreviation should be in capital letters with no space before.

• YES: The sales team just locked in a deal for $110K!
• YES: The sales team just locked in a deal for $110,000!
• NO: The number of Java download requests reached 226,000,000,000 in 2019.
• YES: The number of Java download requests reached 226B in 2019.

Percentages

Use the % symbol instead of spelling out "percent."

Telephone numbers

Use dashes without spaces between numbers. Use a country code if there is a likelihood your reader is in another country.

• YES: 555-867-5309
• NO: (555)-867-5309
• YES: +1-404-123-4567
• NO: +1.404.123.4567

Temperature

Use the degree symbol and the capital F abbreviation for Fahrenheit or C for Celsius.

• YES: 86°F
• YES: 30°C

Time

12-hour clock and 24-hour clock (a.k.a. military time) are both acceptable, and should depend on the audience, at your discretion. 

If using a 12-hour clock, use numerals and AM or PM (always capitalized), with a space in between. Don’t use minutes for on-the-hour time.

• YES: 7 AM
• YES: 7:30 PM
• NO: 7 pm, 7:30PM, 7:30 p.m. 

If using a 24-hour clock, DO use minutes for on-the-hour time, and use a 0 prefix when needed. Omit AM and PM.

• YES: 07:00
• YES: 11:30–13:30
• NO: 7–9:30

Use a hyphen or en dash* with no space on either side between times to indicate a time period.

• YES: 7 AM–10:30 PM
• YES: The collection was available from 2011–2013.
• YES: Monday–Friday, 9 AM–5 PM
• YES: November 10–December 21

Specify time zones when writing about an event or something else people would need to schedule.

Abbreviate time zones within the continental United States as follows:

• Eastern Time: ET
• Central Time: CT
• Mountain Time: MT
• Pacific Time: PT

When referring to international time zones, abbreviations are fine: i.e. GMT, AET. If a time zone does not have a set name, use its Coordinated Universal Time (UTC) offset.

People, Places, and Things

File Extensions

When referring generally to a file extension type, use all uppercase without a period. Add a lowercase s (no apostrophe) to make plural.

• GIF
• PDF
• HTML
• JPGs

When referring to a specific file, the filename should be lowercase:

• slowclap.gif
• MCBenefits.pdf
• ben-twitter-profile.jpg
• ilovedonuts.html

Pronouns

If your subject’s gender is unknown, irrelevant, or preferred as non-gendered, use “they,” “them,” and “their” as a singular pronoun. Don’t use “one” as a pronoun.

When possible avoid the use of pronouns altogether:

• Users
• Management

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 departments and teams (but not the word "team" or "department").

• Marketing team
• Support department

Capitalize individual job titles when referencing to a specific role. Don't capitalize when referring to the role in general terms.

• YES: Our new Marketing Manager starts today.
• YES: All the managers ate donuts.

See also: Capitalization, above.

Don't refer to someone as a “ninja,” “rockstar,” or “wizard” unless they literally are one.

Schools

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.

• Georgia Institute of Technology, Georgia Tech
• Georgia State University (GSU)

States, cities, and countries

US states or countries can either be spelled out or abbreviated with its postal abbreviation (uppercase, no punctuation), but in a single document, be consistent. 

• YES: Fulton, Maryland 
• YES: Fulton, MD 
• YES: London, UK 
• YES: Barcelona, Spain 

Per AP Style, all US cities should be accompanied by their state, with the exception of: Atlanta, Baltimore, Boston, Chicago, Cincinnati, Cleveland, Dallas, Denver, Detroit, Honolulu, Houston, Indianapolis, Las Vegas, Los Angeles, Miami, Milwaukee, Minneapolis, New Orleans, New York, Oklahoma City, Philadelphia, Phoenix, Pittsburgh, St. Louis, Salt Lake City, San Antonio, San Diego, San Francisco, Seattle, Washington.

Street names can be either spelled out or abbreviated in title case with punctuation, but in a single document, be consistent.

• YES: 1234 Grand Apple Boulevard
• YES: 1234 Grand Apple Blvd. 

On the first mention, write out United States. On subsequent mentions, US is fine. The same rule applies to any other country or federation with a standard abbreviation (European Union, EU; United Kingdom, UK).

URLs

When spelling out URLs, leave off the http://www.

Writing About Sonatype

Our company's legal entity name is "Sonatype, Inc." Our trade name is "Sonatype." Use "Sonatype, Inc." only when writing legal documents or contracts. Otherwise, use "Sonatype."

Always capitalize the first “S” in Sonatype.

Refer to Sonatype as “we,” not “it.”

Capitalize branded terms, like Sonatype Nexus Lifecycle. Don’t capitalize descriptive product or feature names, like email or landing pages.

• YES: risk assessment
• YES: vulnerability scan
• YES: Vulnerability Scanner
• YES: OSS Index

Writing About Other Companies

Honor companies’ own names for themselves and their products. Go by what’s used on their official website.

• YES: iPad
• YES: YouTube
• YES: Yahoo!

Refer to a company or product as “it” (not “they”).

Punctuation

Ampersands

In written content, always use and rather than & (unless it's part of a company or brand name).

• NO: Sonatype's products are useful for developers & security teams.
• YES: Sonatype's products are useful for developers and security teams.
• YES: Ben & Jerry’s products are useful for developers and security teams.

NOTE: Within headings and titles, you may use & where appropriate, or as a stylistic alternative.

Apostrophes

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 (i.e. Go get ’em!). This is fine but do it sparingly. You should use an apostrophe, not a single left quote, in these cases. (The apostrophe mark curls in the same direction as a comma.)

NOTE: It’s is a contraction of “it is” or “it has.” Its is a possessive determiner we use to say that something belongs to or refers to something. It’s is the same type of contraction as “where’s” or “there’s,” and its is a possessive just like “my” or “your.”

• YES: Download the document and its addendum.
• NO: Download the document and it’s addendum.

Colons

Use a colon (rather than an ellipsis, em dash, or comma) to offset a list.

• YES: 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 1st word.

• YES: I was faced with a dilemma: I wanted a donut, but I’d just eaten a bagel.

Commas

The following are the typical cases where commas are to be used.

Lists (use Oxford comma):

• YES: Firewall, Repository, and Lifecycle are all parts of the Nexus Platform.
• YES: You’ll need a laptop, a Zoom account, and a good internet connection. 

Between adjectives:

• YES: Click the round, blue button in the corner.
• YES: The end result should be an accurate, user-friendly manual. 

Before conjunctions linking independent clauses:

• YES: I want to run a marathon, but I still have a lot of training to do.
• YES: There are many features to consider, so do your research and choose wisely. 

After introductory words or phrases:

• YES: Before we begin, let’s review what we learned last week.
• YES: This is not, however, always going to be the case. 

Around non-essential clarifying phrases:

• YES: Nexus Lifecycle, a core product in our portfolio, is well-reviewed by customers.
• YES: Vector artwork, which is infinitely scalable, is ideal for logo files. 

Dates and addresses:

• YES: The new report will launch on January 27, 2021.
• YES: Our headquarters are located in Fulton, Maryland. 

Addressing someone directly:

• YES: Michelle, when did you first learn that milk ages differently than wine?
• YES: We’re asking you, our guests, to vote for your favorite conference topic.

Dashes & Hyphens

Dashes/En-Dashes

Dashes should be used for ranges:

• YES: The event runs from November 21–December 1. 
• YES: 20–30 updates are released each tear.

NOTE: Ideally, and en-dash should be used. An en-dash is slightly wider than a hyphen (the width of an “N”). The keystrokes for an en-dash:

• On a PC, hold down the Alt key and type 0150 on the numeric keypad.
• On a Mac, type Option-Hyphen

Em-Dashes

An em-dash is the longest dash (the width of an “M”) and is used to replace commas, parentheses, semi-colons, and colons in an informal setting. A space before and after should be included.

YES: Matt Howard — the CMO of Sonatype — is known for his love of sports, especially golf.

The keystrokes for an em-dash:

• On a PC, press Ctrl+Alt+Minus (on the numeric keypad) or hold down the Alt key as you type 0151 on the numeric keypad.
• On a Mac, type Shift-Option-Hyphen
• In HTML, use the code: #8212;
• In many Microsoft word processing applications, an em-dash will automatically be created when you type two hyphens without a space.

Hyphens

Hyphenate two or more words when they come before a noun and act as a compound adjective.

• YES: She is watching the on-demand webinar.
• NO: She is watching the on demand webinar.

Open source is written as two words, no hyphen (even before a noun), lowercase.

• YES: Protect your open source software.
• NO: Protect your open-source software.

An often overlooked rule for hyphens: The adverb “very” and adverbs ending in “ly” are not hyphenated.

When a compound adjective follows a noun, a hyphen is usually not necessary.

• YES: The webinar is available on demand.
• NO: The webinar is available on-demand.

However, some established compound adjectives are always hyphenated. Double-check with an online dictionary.

• YES: The new tablet is a state-of-the-art design.
• YES: The design of the new tablet is state-of-the-art.

NOTE: An often overlooked rule for hyphens: The adverb “very” and adverbs ending in “ly” are not hyphenated.

• NO: Sonatype has a very-strict dress code.
• NO: The smartly-dressed man left the room.

This rule applies only to adverbs. The following two examples are correct because the “ly” words are not adverbs:

• YES: The friendly-looking dog belongs to Justin.
• YES: Wegman’s is a family-owned business.

Ellipses

When using ellipses as a pause, there should be no space before the ellipsis, and one space after.

• YES: This made me wonder... was I going mad?
• NO: The line to meet baby Yoda moves slowly ... very slowly.

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.”

Emoji and Icons

Emoji and icons are a fun way to add humor, visual interest, or direction to your copy, but use them infrequently and deliberately.

Exclamation Points

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.

Try to limit yourself to one exclamation point per article, email, or other marketing document. When in doubt, avoid!

Periods

Periods go inside quotation marks. They go outside parentheses when the parenthetical is part of a more substantial sentence — additionally, they go inside parentheses when the parenthetical stands alone. Use a single space between sentences.

• YES: Christy said, “I ate a donut.”
• YES: I ate a donut (and I ate a bagel, too).
• YES: I ate a donut and a bagel. (The donut was Sam’s.)

Periods in Headlines

In marketing headlines or subheads, if it’s a full sentence, use sentence case with a period at the end. If it’s not a full sentence, use title case with no period. Whichever way you choose to go with subheads (full sentences or shorter phrases in title case), be consistent.

• YES: You can automatically manage open source risk across your entire SDLC. 
• YES: A Better Way to Build
• YES: Free Open Source Security Index

Question Marks

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.

Quotation Marks

Use quotes to refer titles of short works (like articles and whitepapers), 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.’”

Semicolons

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.

Spaces

Use only one space after a full stop, not two.

Quotations

Editing Quotes

Quotes may be edited for length or clarity, being sure the original intent and stye is intact. Example:

• BEFORE: The reason we picked Lifecycle over the other products is, while the other products were flagging stuff too, they were flagging things that were incorrect. Nexus has low false-positive results, which give us a high confidence factor, which is something we like about it.
• AFTER: The reason we picked Lifecycle over the other products is Nexus has low false-positive results, which gives us a high confidence factor.

Tense

When quoting someone in a blog post or other publication, use the present tense.

• YES: “Using Nexus Lifecycle has changed our perception of open source safety,” says Jamie Smith.
• NO: “Using Nexus Lifecycle has changed our perception of open source safety,” said Jamie Smith.
  
  

When All Else Fails

If you're not sure, or if it's not listed here, use AP Style.