Write using the same, everyday words you use in conversation. If used thoughtfully, contractions sound natural and relaxed and make reading more enjoyable.
- Use common contractions, such as it’s, you’re, that’s, and don’t, to create a warmer, friendlier tone.
- Don’t mix contractions and their uncontracted equivalents in the UI, documentation, or other written collateral. For example, don’t use can’t and cannot in the same UI or document.
- Never form a contraction from a noun and a verb, such as BriteCore’s developing a lot of new services.
Note: It’s okay to form contractions from pronouns and verbs, such as he’s, she’s, we’re, they’ve. Exceptions are noted below.
- Avoid ambiguous or awkward contractions, such as there’d, it’ll, and they’d.
Contractions to use
Table 1: Common contractions acceptable to use in documentation.
|-n't||not||Aren’t, can’t (never cannot), couldn’t, didn’t, doesn’t, don’t, hadn’t, hasn’t, haven’t, isn’t, shouldn’t, weren’t, won’t, wouldn’t|
|-r'e||are||They’re, we’re, you’re|
|-'s||is||He’s, let’s, she’s, that’s, there’s, what’s, where’s, who’s|
Reminder: Don’t form a contraction from a noun and a verb. Pronouns (he, she, it, etc.) are acceptable.
|-'ve||have||Hey’ve, you’ve, we’ve, I’ve|
Exception: Don’t use what’ve or who’ve. In instances where these contractions are passive voice, consider rewriting in active voice.
Don’t use the contractions in Table 2. They’re either archaic, confusing/ambiguous (for example, they’d could mean they would or they had; it’ll could mean it will or it shall), or too informal (…BriteCore features that’re used the most…). Some simply sound or look awkward. Always use your best judgment to avoid uncommon, colloquial, confusing, or dated words.
Contractions to avoid
Table 2: Contractions to avoid in documentation.
|-'d||Had, would||They’d, it’d, you’d, we’d, I’d, he’d, she’d|
|-'ll||Will, shall||They’ll, it’ll, you’ll, we’ll, I’ll, he’ll, she’ll, how’ll|
|Exceptions to -n't||not||Mayn’t, mustn’t, mightn’t, shan’t, oughtn’t|
|Exceptions to -'re||are||That’re, there’re, these’re, those’re, what’re, where’re, which’re, who’re, why’re, how’re, any noun + -’re|
|Double contractions||Varies||Couldn’t’ve, mustn’t’ve|