Grammar and Mechanics
Writing Basics
- Write like you speak and use simple words. Concise language is always easier to understand.
- Make sentences shorter and break up long sentences. Again, conciseness rules the day in written communication.
- Write to an audience of one. A single individual reads everything we write.
- Avoid unnecessary jargon. If you’ve heard it a million times before, there's a better way to say it.
DO
Send a notification
…to protect your application.
DON’T
Trigger an integration
…to meet your needs.
Remove Preambles
DO
Legacy solutions result in false positives.
DON’T
The reason we went this route is because legacy solutions result in too many false positives.
Be concise. Remove any sentences or phrases without inherent value.
DON’T
With Signal Sciences, Shinola found these benefits.
On this page, we’ll discuss…
Moving forward…
Grammar
Active Voice
Write in active voice to make sentences strong and clear. A sentence with a subject should act upon its verb.
DO
The agent analyzes the tokenized representation of the request
DON’T
The tokenized representation of the request is analyzed.
Emojis
We don't use emojis at Signal Sciences 🙅♀️. Do not use them in any marketing communication (including social media) or product interface. We use emojis in product blankslates but are phasing them out.
Personal Pronouns
Speak to users in the second person (you, your). Use second person when giving instructions, describing features, and asking questions.
DO
Choose the emails you want to receive in your Account Settings
DON'T
Choose the emails you want to receive in my Account Settings
Use the first person singular (I, me, my) for specific use cases, such as accepting terms of service.
DO
I accept the consequences of deleting a site
DON'T
You accept the consequences of deleting a site
In the console, try to avoid using first person plural (our, we). If the product is performing the action, say “Signal Sciences” instead. Using first person plural is OK within emails and blog posts, since we are directly speaking to users from our own point of view.
DO
Signal Sciences redacts sensitive data
Signal Sciences will convert an IP into an anonymized IPv6 by performing a one-way hash
DON'T
We redact sensitive data
We will convert an IP into an anonymized IPv6 by performing a one-way hash
Mechanics
Ampersands
Do not use ampersands in a sentence. Using an ampersand in a sentence breaks up the flow of a conversational sentence and makes the sentence sound unnatural.
DO
Enhance your rules with corp lists and signals
DON’T
Enhance your rules with corp lists & signals
Use Ampersands in the console solely for navigation, titles, and labels.
DO
Help Guides & FAQ
DON’T
Help Guides and FAQ
Apostrophes & Posession
For Signal Sciences, avoid using a possessive apostrophe unless describing something we’re pursuing.
Do not use the term "Signal Sciences's". It's technically correct to spell it that way, but it looks terrible.
DO
- Signal Sciences'
- Signal Sciences’ growth
- Signal Sciences RASP, Signal Sciences WAF
- Signal Sciences products
- Signal Sciences employees
DON’T
- Signal Sciences's
- Signal Sciences’ Web Protection Platform
- The Signal Sciences’ business plan
If a word is a singular noun (even if it ends in an s), add 's. If a word is a plural noun, just add an '
DO
users'
DON’T
users's
Casing & Capitalization
Title case capitalizes the first letter of every word except for articles, prepositions, and conjunctions.
Use title case for:
- Proper nouns
- Navigation and page titles (including breadcrumbs)
- Modal titles
- Signal names
- Page titles in sentences (Don't capitalize the word "page")
DO
You can connect to Slack on the Site Integrations page
DON’T
You can connect to slack on the site integrations page
Sentence case capitalizes the first letter of the first word.
Use sentence case for most copy in the console:
- Subtitles
- Buttons
- Blankslates
- Forms
Use lowercase for:
Keep departments lowercase unless referring to DevSecOps.
DO
operations, security, engineering
IT operations and engineering
DevSecOps, DevOps
DON’T
Operations, Security, Engineering
IT Operations and Engineering
devsecops, devops
Keep job titles lowercase unless it comes directly in front of the person's name.
DO
Justin is a product manager who works with designers and engineers
The Vice President of Product Management, JD, works with designers and engineers
DON’T
Justin is a Product Manager who works with Designers and Engineers
The vice president of product management, JD, works with designers and engineers
Keep feature names and agent modes lowercase (e.g., rules, lists, blocking mode).
DO
You can change your agent configurations to blocking mode on the Site Settings page
DON’T
You can change your Agent Configurations to Blocking Mode on the site settings page
Keep corp and site lowercase.
DO
Manage all the users in your corp
DON’T
Manage all the users in your Corp
Keep roles lowercase.
DO
For help, contact your corp owner
DON’T
For help, contact your Corp Owner
Cloud Capitalization rules
DO
Use “cloud” with lower case ‘c’ when referring to cloud computing.
Use “Cloud” with upper case ‘C’ when used as part of a proper noun:
- Cloud Native Security Summit (a specific event)
- Cloud WAF (a specific deployment option)
- Cloud Security (this is a specific kind of security, as opposed to Endpoint Security, Identification Access Management etc.)
Colons
- Use colons after a complete sentence to introduce a list of items or a bulleted list.
- Don't use colons to introduce a list of radio buttons or checkboxes.
DO
We support 3 types of corp integrations:
- Mailing lists
- Slack
- Microsoft Teams
We support 3 types of corp integrations: mailing lists, Slack, and Microsoft Teams
DON’T
We support 3 types of corp integrations
- Mailing lists
- Slack
- Microsoft Teams
We support 3 types of corp integrations, mailing lists, slack, and microsoft teams
Commas
Always use the oxford comma. In a series, always include a comma before the last item in the series.
(Note: You don't need to use the oxford comma in tweets or press releases where there is a restriction on number of characters)
DO
Any app, any attack, and any DevOps toolchain
DON’T
Any app, any attack and any DevOps toolchain
Use a comma after e.g.,
DO
e.g., email, Datadog
DON’T
e.g. email, Datadog
Use commas with independent clauses
DO
The security team tried Signal Sciences, and engineering approved the spend.
DON’T
The security team tried Signal Sciences and engineering approved the spend.
Commas should always go inside of quotation marks.
DO
“Signal Sciences was the one solution that met our requirements,” said One Medical’s CISO.
DON’T
“Signal Sciences was the one solution that met our requirements”, said One Medical’s CISO
Contractions
Use contractions to make copy sound casual and human. Common contractions may be used liberally, but don't use contractions if they sound old timey or awkward to say out loud.
DO
- you're
- don't
- can't
- won't
- it's
- aren't
- you'll
DON’T
- could've
- mustn't
- that'll
Ellipses & Truncation
For the console:
- Ellipses suggest incompleteness. Use them to signify truncation.
- Use ellipses to signify that the user may start typing into a search or filter bar.
- Use ellipses after “select…” in dropdowns
DO
Search by name, email, or role…
Select…
DON’T
Search by name, email, or role
Select
En Dashes & Em Dashes
- There should never be spaces around en dashes and em dashes. Be careful not to mix these up with hyphens.
- Use En dashes solely for date ranges and number ranges.
- Use Em dashes to emphasize a pause.
DO
No matter your role—or online protection needs—Signal Sciences is for you.
DON’T
No matter your role-or online protection needs-Signal Sciences is for you.
Exclamation Points
For the console:
- Avoid exclamation points, even in success messages.
- Exclamation points are appropriate for congratulating a user on completing major onboarding set up tasks, such as setting their site in blocking mode or installing agents.
- If you add an exclamation mark, use no more than 1 per sentence.
DO
You set your site in blocking mode. Well done!
DON’T
Success!! Your profile has been updated
Hyphens
- There should never be spaces around hyphens.
- Use Hyphens for compound modifiers, which are two or more words that join together to modify a noun.
DO
- Application-specific detection
- Real-time blocking
DON'T
- Application specific detection
- Real time blocking
Below is a list of how to write words that use or shouldn't use hyphens:
HYPHENATION
- cloud first (no hyphen)
- cross-site scripting
- email (no hyphen)
- false positives (no hyphen)
- multi-factor authentication
- next-gen WAF
- re-enter
- resend
- runtime application self-protection
- single sign-on
- two-factor authentication
Periods
Always use periods when a piece of prose has 2 or more sentences. For other situations in the console, periods aren't needed. It's easier for readers to scan text without unnecessary punctuation.
Don't use periods in single sentences for:
- Subtitles
- Bulleted or numbered lists
- Forms
- Blankslates
- Validation or error messages
Never use a period after:
- Titles
- Buttons
- Standalone links, unless the link is part of a sentence.
- Labels
DO
Monitor a timeline of flagged IPs over the last 30 days. Learn more
DON'T
Monitor a timeline of flagged IPs over the last 30 days. Learn more.
String Formatting
FormattedBytes
- File size units of measurement should be uppercase.
- No spaces between the number and the unit of measurement.
- A file size of "0" should have "B" appended to it so the unit of measurement is unambiguous.
- Units expressed in bytes should always be whole numbers.
EXAMPLES
- 21.3KB
- 17B
- 2.5MB
- 284GB
- 0B
FormattedNumbers
- Always use numerals to represent numbers.
- Use commas for numbers with four or more digits. (Rationale: It is easier to read numbers with delimiters - significants and scale are easily recognized that way.)
- Only compact numbers in cases where you are extremely space-constrained, or in reports whose purpose is to summarize top-line data.
- Compact numbers should always use lowercase symbols to indicate the magnitude of the number.
- Compact numbers should support an HTML title attribute with the full number.
- When using decimals, always round to the hundreds place.
EXAMPLES - FULL NUMBERS
- 9
- 100
- 0
- 4,529
- 2,320,008
EXAMPLES - COMPACT NUMBERS
- 12.12b
- 5m
- 395k
- 12.35k
- 1.79k
FormattedPercent
- By default, round percentages to whole numbers. Use decimals when precision adds clarity or insight to the experience.
- When not using precision, represent values less than 0.5% and greater than 0% as <1%.
- When using precision, always round decimals to the hundredth place.
- When using precision, percentages less than 0.01% are insignificant enough that they should be represented as
<0.01%. - No spaces between the number and the percentage symbol.
EXAMPLES
- 100%
- 23%
- <1%
- 0%
- 0.01%
- <0.01%
FormattedDuration
- When working with time scales of less than one second, always use the lowercase abbreviation for milliseconds ("ms").
- When working with time scales of one second or greater:
- Whenever possible, don't abbreviate the time scale.
- If space constraints require time unit abbreviation, use singularized lowercase abbreviations.
- Always singularize the time scale when expressing a single unit.
- Always write time scales in lowercase.
- Express durations as integers.
EXAMPLES - FULL TIMES
- 56 ms
- 30 seconds
- 1 minute
- 20 hours
- 30 days
- 1 month
- 2 years
EXAMPLES - ABBREVIATED TIMES
- 56 ms
- 2 sec
- 5 min
- 6 h
- 3 d
- 2 wk
- 6 mo
- 3 y
FormattedRelativeTimes
- Always adapt to duration and display time units accordingly. (e.g. after 30 days, display months; after 12 months, display years).
- Relative timestamps require some mental work on the part of the user; always write time units out in full for clarity.
- Always singularize the time scale when expressing a single unit.
EXAMPLES
- 29 seconds ago
- 1 minute ago
- 59 minutes ago
- 1 day ago
- 29 days ago
- 1 month ago
- 2 years ago
FormattedTime
- Use the 12-hour clock.
- Always follow times with an uppercase “AM” or “PM”. Do not use periods (e.g., “A.M.”).
- Always insert a single space between the time and “AM” or “PM”.
- Always convert UTC to local time.
- When indicating the time zone, use the time zone’s abbreviation in uppercase (e.g. "GMT") and place it after am or pm with a single space preceding it.
- To show a time range, use an en dash and include the am/pm after both times.
EXAMPLES
- 2:00 PM EDT
- 12:32 PM GMT
- 11:59 AM NZDT
- 1:00 PM-2:30 PM BRT
FormattedDate
- Never use ordinal indicators (e.g., "11" not "11th").
- To make date string lengths more consistent, prepend a 0 in front of single-digit dates (e.g., "03" not "3").
- Use the month's full name whenever possible.
- Always capitalize the first letter of the month.
- If space constraints require abbreviating the month, use the 3-letter abbreviation.
- Don't write dates numerically.
- Separate the month and day from the year with a comma.
- Express date ranges with a single en dash with no spaces.
EXAMPLES
- November 05, 2017
- Nov 05, 2017
- Jan 23, 2017–Apr 01, 2017