Bugcrowd design system: Tone & language

This guide helps you write clear and simple text for Bugcrowd’s user interfaces that is:

  • simple
  • user-focused
  • inclusive
  • scannable
  • unambiguous
  • accessible on varying screen sizes
  • and consistent.

Writing for users

Last updated: Oct 11, 2019

Research the users you are writing for.

When writing, research:

  • User behavior
    • What do users wish to achieve?
    • What blocks them from achieving their goal?
  • Use contexts
  • User vocabulary — use the same terms and phrases that they use to search and scan information.

Writing style

Last updated: Oct 11, 2019

Simplify text to build consistent clarity in instruction and understanding of the software functionality.

Use common or plain English

Write simple sentences, and use simple phrasing. This:

  • Improves comprehension
  • Is easier to translate — English may not be the first language for many of our users
  • Helps users make better decisions;
  • Builds trust with users.

Rework a sentence over several iterations.

Consider breaking down sentences with comma-separated items into a simple list.

Use a simple, present, and active voice

Use active voice over a passive voice — focus on the main verb’s agent.

For example:

Active voice Passive voice
The quokka carried its baby in her pouch. The baby was carried by the quokka in her pouch.
A researcher found a vulnerability. A vulnerability was found by a researcher.
The company requires security audits to meet compliance every year. To meet compliance the company requires security audits every year.

Otherwise:

  • Use present tense (for example “Returns a value” and “Will return a value…”)
  • Use common contractions for an informal voice (for example “it’s” and “you’re”) but avoid obscure ones (for example “you’d”)
  • Avoid using gerunds (-ings) for more consise language (for example “using” → “use”).

Write inclusively

Beware of tight measures

The measure of a line of text is its width.

Avoid long sentences and paragraphs. This is especially important when the measure is short relative to the font size.

Like with newspaper copy, long runs of text in a panel with a short measure are more difficult to read due to readjustment of the eye from line to line down a thin column.

Perspective of voice

Last updated: Oct 11, 2019

Use a third-person, neutral perspective of voice.

Generally avoid a first-person perspective of voice (not using “I” or “we”).

Use a first-person perspective for:

  • Legalese (for example “I hereby …”)
  • Bugcrowd services (for example “We use these details to get you payments and let you manage them”).

Use a second-person persective when addressing the user directly.

Only use possessives in Hint text when referring to the user, for example:

  • “Get paid through a direct deposit to your account”
  • “Your active sessions are listed below”
  • “If you believe your account may have been compromised …”.

Don’t use possessives in titles or labels.

For example, write navigation menus like this:

  • Invites
  • Account settings
  • Support
  • Log out

Don’t do this:

  • “Your invites” or “My invites”
  • “Your account settings” or “My account settings”
  • “Our support”

Spelling

Last updated: Oct 11, 2019

Write in American English

Use American English.

Headings & titles

Use sentence case for titles and headings, capitalizing only the opening word and proper nouns.

Capitalization

  • Write in sentence case
  • Avoid full capitalization for readability reasons

Use title case for proper nouns, for example:

  • Ada Lovelace
  • The Bureau of Meteorology
  • Learn how to hack
  • Rules of engagement
  • Hacking with Bugcrowd

Capitalize Bugcrowd’s products and services as proper nouns.

Spell and capitalize features as they are spelled by the section of the application or the headings of the pages they exist in.

Also see Glossary, below.

Numbers

Use digits instead of words unless it would be unconventional, for example:

  • “one or two submissions”
  • ordinals (first, second, …) — dates excepted.

Add a comma between the third and fourth digit from the right, for numbers 10,000 and above.

Use the word million instead of digits.


Guidance adapted from the Australian Government’s Digital Content Guide Writing style: Numbers and measurements entry.

Punctuation

Last updated: Oct 11, 2019

Write simple sentences to avoid complex punctuation.

Periods

Periods in headings

Don’t use a period at the end of a heading.

Periods in lists

Avoid periods in simple lists.

  • If the simple list is prefaced (such as with “For example:”) only give the final list item a period
  • If the list is simple and unprefaced don’t use periods
  • If a list must consist of multiple sentences use periods as normal

Commas

  • Use commas sparingly
  • Use Oxford commas to avoid confusion
  • Don’t punctuate dates (for example, “2 October, 2019” → “Wednesday 2 October 2019”)

Apostrophes

Use apostrophes for:

  • Omissions, such as contractions (for example “we’ll”)
  • Possessive nouns (for example “in one month’s time”)
  • Marking plural characters (for example “p’s” and “q’s”).

Don’t use apostrophes for plural abbreviations or decades (for example CDs or 1990s).

Quotation marks

Use proper quotation marks — , , , — instead of prime marks (', ").

  • Use single quotation marks when quoting a person or a source, or to punctuate unusual or colloquial expressions
  • Use double quotation marks when quoting within a quote

Hyphens

Only use hyphens (-) for hyphenation.

  • Use a hyphen when the second word is “up” or when the first and second words end and start with the same letter
  • Don’t use a hyphen if the first word of a compound is an adverb ending in “ly”
  • Don’t hyphenate “login” or “sign in”

En dashes

Use en dashes () only for denoting ranges (for example “1 – 100”), however prefer using “to” instead (for example “1 to 100”).

Where possible thin-space the en dash (via its HTML entity code).

Em dashes

Use em dashes () sparingly to add a related idea to a sentence — use with care to avoid creating very long sentences.

Use regular spaces on either side of the em dash.

Semicolons

Avoid using semicolons — use simpler sentences, em dashes, or a list instead.

Other punctuation

  • Use ellipses () when deliberately ommitting or truncating something
  • Only use the at-sign (@) for email addresses, social media handles, and @mentions
  • Don’t use exclamation marks

Abbreviations

Last updated: Oct 2, 2019

Acronyms

Use the HTML5 <abbr> element to mark up abbreviations.

Wrap the first instance of that <abbr> in a definition element (<dfn>) which represents the defining instance of that term.

Ampersands

Limit use of ampersands to headings, subheadings, and navigation labels or graphics.

Latin abbreviations

Avoid Latin abbreviations.

Instead use expanded English, for example:

  • “eg” → “for example” 🙃
  • “etc” → rewrite so the user doesn’t have to guess what “etc” may refer to, include, and exclude.

Don’t use “ie”, “nb”, “cf”, “viz” or other more obscure abbreviations.

Plain English substitutions

Last updated: Oct 2, 2019

Table adapted from the Australian Government’s Digital Content Guide Writing style: Plain English entry.

Don’t write this Write this instead
a number of some, many, few
address this issue look for solutions, solve this problem
approximately about
adequate number of enough
aggregated total
amongst among
as a consequence of because
ascertain find out
assist help
at a later date later
at this point in time now
cognisant of aware of, know
commence start, begin
concerning about
consequently so
create a dialogue with speak to
deliver, drive say what you are doing, for example “testing …”
despite the fact that although
disburse pay
discontinue stop
dispatch send
documentation documents (unless referring to software documentation)
due to the fact that because, since, as
during the month of August in August
establish create, set-up, form
examine look at, check, discuss
facilitate help
give consideration to think about, consider
going forward future
have the capacity to can
identify set, create, decide on, know, recognise
if this is not the case if not
if this is the case if so
impact upon affect
in accordance with in line with
implement apply, install, do – where possible be specific
in order to to
in receipt of get, have, receive, receiving
in relation to about
in the event of, in the event that if, when
in the light of, in view of because of
it is requested that you declare you should declare
it should be noted that note that, remember that
key, important, primary main
leverage use, build on
make an application apply
make a complaint complain
methodology method
notwithstanding even though, though
obtain get, have
prior to before
primary main
provide give
provide a response to respond to
provide assistance with help
pursuant to under
reach a decision decide
require need or must
subsequently after
that is the reason why that is why
the way in which how
the reason is because because, the reason is
thereafter then, afterwards
until such time as until
upon on
utilise use
whether or not whether
with reference to, with regard to, with respect to about, regarding