Tone & language

Last modified:

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 modified:

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 modified:

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


  • 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 concise 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.

Last modified:

Rule of thumb: write link text that makes sense when read out of context in isolation.

Use links to help users navigate content (for example, between landmark regions) and to support user journeys.

On public-facing pages good links improve document semantics and search engine optimization.

Use text

Use text in links.

When adding links within paragraphs, try placing links at the end of sentences.

When linking to an email address via mailto: use the full email address as the link text.

If using images, ensure the image has understandable alt text.

Do not refer to the method of interaction (for example “click here”) in link text.

Users interact with links in many ways, including via keyboard, mouse, or via touch.

When talking about a link or giving instruction, use “select” as the verb.

Make the destination clear even out of context

Write link text that makes the destination clear.

The link text should be understandable when read out of context of surrounding content, for example:

Don’t write thisWrite this
Click here to join.
Click here to sign in.
Sign up as a Bugcrowd Researcher.
Don’t have an account? Create an account.
Already have an account? Log in.
Become a Bugcrowd Researcher.
Download the 2024 Lorem Ispum Dolor report.Download the 2024 Lorem Ispum Dolor report (PDF).

This is requirement for WCAG success criterions:

  • 2.4.4 Link purpose (in context) — level A
  • 2.4.9 Link purpose (link only) — level AAA

Use links sparingly and with purpose.

  • Be explicit when linking to product documentation.
  • Use “deep” linking where appropriate and possible, linking directly to a page or content on a page via its ID.
  • Link to existing authoritative resources instead of duplicating them.

Open links in the same browser tab or window instead of force opening a new window or tab.

This is the default behavior of hyperlinks and maintains browser Back button functionality.

If necessary — such as for logon interstitials or previewing a document — indicate the change in behavior where possible.

Perspective of voice

Last modified:

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


Last modified:

Write in American English

Use American English.

Headings & titles

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


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


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.


Last modified:

Write simple sentences to avoid complex punctuation.


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 not prefaced don’t use periods
  • If a list must consist of multiple sentences use periods as normal


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


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


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.


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

Other punctuation

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


Last modified:


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.


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.

Date and time

Last modified:

Write dates and times consistently to reduce confusion for our global users.

This guidance describes formatting (human-readable) dates and times in short-form, long-form, and relatively (eg. “2 hours ago”).

Use this guidance to configure the ISO formatting output of datetime libraries. Use standardized front-end datetime helpers that emit the “(date) time <time>” element.

Standard date format

Use the full humanized formatting when using dates in sentences or headings.

We usually format starting with the day, month, then the year. So on the 2nd day of the month October, in the year 2022, the date can be written as:

  • 2 Oct 2022
  • Wed 2 Oct 2022
  • 2 October 2022
  • Wednesday 2 October 2022
  • Don’t punctuate dates (for example, “2 October, 2022” → “Wednesday 2 October 2022”)
  • Write dates as cardinal numbers (2 October), not ordinal numbers (2nd October).
  • You can omit the year if the event occurs on the same year (for example, “2 October”, or “Wednesday 2 October”)

Use the shorter ISO 8601 format for setting many dates together such as in a table, as subdued/hint text where space is limited, or as tertiary information. This is interpreted as YYYY-MM-DD, for example:

16 January 2022 is represented as 2022-01-16

Standard time format

Use ‘am’ and ‘pm’ in lowercase when referencing time in sentences or headings with a space in between. This is interpreted as HH:MM am/pm for example:

  • 2:30 pm
  • 9:15 am
  • Remove the proceeding ‘0’ in single digit hours (for example, “02:30 pm” → “2:30 pm”)

Use the 24 hour time format when referring to system-driven communication such as outages or system time. This is interpreted as HH:MM and in some instances where the exact time is critical, HH:MM:SS, for example:

  • 14:30
  • 22:59:46
  • 06:45:20
  • Keep the proceeding ‘0’ in single digit hours (for example, “4:13” → “04:13”)


All dates and times presented to the user should be localized in their own timezone relative to the Coordinated Universal Time (UTC).

When humanizing a relative date and time, supplement it with a tooltip expanding the reference time and date in the users local timezone. For example:

  • 6 days ago (tooltip: “2022-03-30, 04:41:06 UTC”)
  • 3 weeks ago (tooltip: “2022-07-16, 08:59:18 AEST)

Date and time ranges

When displaying date or time ranges, use ‘to’ — not hyphens, en or em dashes, for example:

  • 2 Oct 2022 to 30 Oct 2022
  • 2:30 pm to 7:45 am
  • 15:15 to 07:55
  • Use a single am or pm if both times occur in am or pm (for example, 6:30 to 7:45 am)

Displaying date and time together

When displaying date and time, format starting with date then time and a comma between the date and time, for example:

  • Sunday 25 October 2022, 7:41 pm
  • 2022-05-25, 18:35

Date time quick reference guide

Date and time formats- Wednesday 2 October 2022, 7:41 pm
- Wed 2 Oct 2022, 7:41 pm
- 2 Oct, 7:41 pm (If it occurs in the same year)
- 2022-10-02, 07:41
Use 24 hour time formats or am/pm- 14:30
- 2:30 pm
When referencing a relative date and time- 2022-03-30, 04:41:06 ET
- 30 Mar 2022, 04:41:06 AEST
- 30 March 2022, 04:41:06 UTC
Numeric dates- 2022-10-02
- 2022-04-14
Date ranges- 2 Oct 2022 to 22 Nov 2022
- 2022-04-14 to 2022-07-01
Time ranges- 14:30 to 19:45
- 5:55 to 8:27 am
- 2:19 am to 3:54 pm
Truncated date formats- Fri 5 Jan 2022
- 5 Jan 2020
- 2022-01-05

Plain English substitutions

Last modified:

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

Don’t write thisWrite this instead
a number ofsome, many, few
address this issuelook for solutions, solve this problem
adequate number ofenough
as a consequence ofbecause
ascertainfind out
at a later datelater
at this point in timenow
cognizant ofaware of, know
commencestart, begin
create a dialogue withspeak to
deliver, drivesay what you are doing, for example “testing …”
despite the fact thatalthough
documentationdocuments (unless referring to software documentation)
due to the fact thatbecause, since, as
during the month of Augustin August
establishcreate, set-up, form
examinelook at, check, discuss
give consideration tothink about, consider
going forwardfuture
have the capacity tocan
identifyset, create, decide on, know, recognize
if this is not the caseif not
if this is the caseif so
impact uponaffect
in accordance within line with
implementapply, install, do – where possible be specific
in order toto
in receipt ofget, have, receive, receiving
in relation toabout
in the event of, in the event thatif, when
in the light of, in view ofbecause of
it is requested that you declareyou should declare
it should be noted thatnote that, remember that
key, important, primarymain
leverageuse, build on
make an applicationapply
make a complaintcomplain
notwithstandingeven though, though
obtainget, have
prior tobefore
provide a response torespond to
provide assistance withhelp
pursuant tounder
reach a decisiondecide
requireneed or must
that is the reason whythat is why
the way in whichhow
the reason is becausebecause, the reason is
thereafterthen, afterwards
until such time asuntil
whether or notwhether
with reference to, with regard to, with respect toabout, regarding


Last modified:

Use the spelling of industry and technical terms as given in the Bugcrowd Glossary.