Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix(docs): fix formatting issues in dev docs #1319

Merged
merged 3 commits into from
Dec 12, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions packages/docs/design-docs/ux-writing/glossary.mdx
Original file line number Diff line number Diff line change
@@ -130,8 +130,14 @@ Never use check-out.
</dd>

<Dos>
<div className="hidden">Do</div>- Ready to check out? - When you’re done shopping, proceed to the
checkout. - Navigate to the checkout page.
<div className="hidden">Do</div>
<div>

- Ready to check out?
- When you’re done shopping, proceed to the checkout.
- Navigate to the checkout page.

</div>
</Dos>

<dt className="font-bold mt-4">
43 changes: 35 additions & 8 deletions packages/docs/design-docs/ux-writing/grammar.mdx
Original file line number Diff line number Diff line change
@@ -55,18 +55,21 @@ NN/g still recommends writing out numbers that don’t represent specific data.
Try to use the active voice. It’s simpler and more direct than the passive voice. Not sure what the difference is between active and passive? Here are some examples:

<ComparisonTable>
| Active | Passive | | --- | --- | | Choose a payment method | Choose the preferred payment method
| | We recommend… | It is recommended… | | Turn on the setting | The setting should be turned on |

| Active | Passive |
| ----------------------- | ----------------------------------- |
| Choose a payment method | Choose the preferred payment method |
| We recommend… | It is recommended… |
| Turn on the setting | The setting should be turned on |

</ComparisonTable>

As you can see, with the passive voice it’s not clear who the subject is and who’s doing the acting. It’s indirect, confusing and wordy. Granted, writing in the active voice can sometimes feel too direct, even a little bossy. Users, however, appreciate it when you give them the info they need without a lot of fluff.

Of course, there are exceptions to the rule. Here’s when it might be okay to use the passive voice:

- To avoid referencing BigCommerce or your app by name when doing so would be distracting

- To make it clear that BigCommerce or your app didn’t personally take an action or make a decision; rather, the software took the action

- If the object or the action are more important than the subject doing the action

<DosAndDonts>
@@ -83,11 +86,22 @@ A plurality occurs when the copy changes depending on the number of items you’
<DosAndDonts>
<Dos>
<div className="hidden">**Do**</div>
<div>- You have a new message. - You have 10 new messages.</div>
<div>

- You have a new message.
- You have 10 new messages.

</div>
</Dos>
<Donts>
<div className="hidden">**Don't**</div>
<div>- You have a new message or messages. - You have a new message(s)</div>
<div>

- You have a new message or messages.
- You have a new message(s).

</div>

</Donts>
</DosAndDonts>

@@ -102,12 +116,25 @@ Past participles usually end with “-ed,” “-d,” “-t,” “-en” or
<DosAndDonts>
<Dos>
<div className="hidden">**Do**</div>
<div>- Settings saved - App installed - Payment failed - Message sent</div>
<div>

- Settings saved
- App installed
- Payment failed
- Message sent

</div>
</Dos>
<Donts>
<div className="hidden">**Don't**</div>
<div>
- Settings have been saved - App was installed - Payment has failed - Message was sent

- Settings have been saved
- App was installed
- Payment has failed
- Message was sent

</div>

</Donts>
</DosAndDonts>
67 changes: 45 additions & 22 deletions packages/docs/design-docs/ux-writing/interactions.mdx
Original file line number Diff line number Diff line change
@@ -39,28 +39,30 @@ Avoid linking entire sentences. Instead, link only the most relevant portion of
Links outside of a sentence should follow the &#123;verb&#125; + &#123;noun&#125; format. Do not use periods or exclamation points. Question marks are fine within the context of a forgotten password link. Otherwise, avoid using them.

<DosAndDonts>
<Dos hideHeader={true}>
<div className="hidden">
**Do**
</div>
<div>
[Forgot password?](https://www.bigcommerce.com/ "https://www.bigcommerce.com/")
<Dos>
<div className="hidden">
**Do**
</div>
<div>

[Learn more](https://www.bigcommerce.com/ 'https://www.bigcommerce.com/')
- [Forgot password?](https://www.bigcommerce.com/ "https://www.bigcommerce.com/")
- [Learn more](https://www.bigcommerce.com/ 'https://www.bigcommerce.com/')

</div>
</Dos>
<Donts hideHeader={true}>
<div className="hidden">
**Don't**
</div>
<div>
[Learn more.](https://www.bigcommerce.com/ "https://www.bigcommerce.com/")
</div>

</Dos>
<Donts>
<div className="hidden">
**Don't**
</div>
<div>

[Edit settings!](https://www.bigcommerce.com/ 'https://www.bigcommerce.com/')
- [Learn more.](https://www.bigcommerce.com/ "https://www.bigcommerce.com/")
- [Edit settings!](https://www.bigcommerce.com/ 'https://www.bigcommerce.com/')

</div>
</Donts>
</div>

</Donts>
</DosAndDonts>

### External links
@@ -91,8 +93,18 @@ Users should know exactly what will happen when they click. Button language shou
- Use sentence case and never include ending punctuation

<Dos>
<div className="hidden">**Do**</div>- Learn more - Start trial - Save settings - Customize
dashboard - View more - Add new - Create channel
<div className="hidden">**Do**</div>
<div>

- Learn more
- Start trial
- Save settings
- Customize dashboard
- View more
- Add new
- Create channel

</div>
</Dos>

## Information patterns
@@ -149,6 +161,17 @@ When deprecating an older feature it’s important to set the right tone. Callin
When writing about the checkout process, follow established patterns. Ecommerce has been around long enough that users have strong expectations about what the process should look like.

<Dos>
<div className="hidden">**Do**</div>- Add to cart - Check out - Check out securely - Go to
checkout - View cart - Edit cart - Confirm payment - Place order
<div className="hidden">**Do**</div>
<div>

- Add to cart
- Check out
- Check out securely
- Go to checkout
- View cart
- Edit cart
- Confirm payment
- Place order

</div>
</Dos>
16 changes: 13 additions & 3 deletions packages/docs/design-docs/ux-writing/localization.mdx
Original file line number Diff line number Diff line change
@@ -56,7 +56,17 @@ Symbols like “#” and “&” don’t carry the same meaning in every languag
Here are some British English words and phrases, common to ecommerce, and American English equivalents you should use instead.

<ComparisonTable>
| American | British | |---|---| | Buy online, pick up in-store | Click and collect | | Canceled |
Cancelled | | Center | Centre | | Color | Colour | | Fulfill | Fulfil | | Gray | Grey | | Organize
| Organise | | Meter | Metre | | Ship, mail | Post |

| American | British |
| ---------------------------- | ----------------- |
| Buy online, pick up in-store | Click and collect |
| Canceled | Cancelled |
| Center | Centre |
| Color | Colour |
| Fulfill | Fulfil |
| Gray | Grey |
| Organize | Organise |
| Meter | Metre |
| Ship, mail | Post |

</ComparisonTable>
112 changes: 81 additions & 31 deletions packages/docs/design-docs/ux-writing/mechanics.mdx
Original file line number Diff line number Diff line change
@@ -100,7 +100,14 @@ Use the 3-letter month abbreviations: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Se
Use day-of-the-week abbreviations: Mon, Tue, Wed, Thu, Fri, Sat and Sun. Do not use a period after the day when abbreviating.

<Dos>
<div className="hidden">**Do**</div>- Jan 5, 2022 - 1/02/22 - Mon, Jan 5, 2022
<div className="hidden">**Do**</div>
<div>

- Jan 5, 2022
- 1/02/22
- Mon, Jan 5, 2022

</div>
</Dos>

**Time**
@@ -110,29 +117,49 @@ Don’t use periods in “AM” and “PM”
Be sure to check the region’s time zone and if it’s daylight savings time or not. For example, CDT is Central Daylight Time and CST is Central Standard Time.

<DosAndDonts>
<Dos>
<div className="hidden">**Do**</div>
<div>- 2:00 AM CST - 3:30 PM CDT</div>
</Dos>
<Donts>
<div className="hidden">**Don't**</div>
<div>- 2:00am CST - 3:30 P.M. CDT</div>
</Donts>
<Dos>
<div className="hidden">**Do**</div>
<div>

- 2:00 AM CST
- 3:30 PM CDT

</div>
</Dos>
<Donts>
<div className="hidden">**Don't**</div>
<div>

- 2:00am CST.
- 3:30 P.M. CDT.

</div>
</Donts>
</DosAndDonts>

**Phone numbers**

Use hyphens to break up phone numbers. Don’t use parentheses or periods.

<DosAndDonts>
<Dos>
<div className="hidden">**Do**</div>
<div>- 1-888-555-5555</div>
</Dos>
<Donts>
<div className="hidden">**Don't**</div>
<div>- 1 (888) 555-5555 - 1.888.555.5555</div>
</Donts>
<Dos>
<div className="hidden">**Do**</div>
<div>

- 888-555-5555
- 1-888-555-5555

</div>
</Dos>
<Donts>
<div className="hidden">**Dont**</div>
<div>

- 1 (888) 555-5555
- 1.888.555.5555

</div>
</Donts>
</DosAndDonts>

### Exclamation point
@@ -167,18 +194,28 @@ En dashes are used to indicate a range between two numbers. Don’t put spaces a
If the number range is preceded by the words “from,” or “between,” then use the word “to” instead of an en dash.

<Dos>
<div className="hidden">**Do**</div>- There are 500–1000 employees at BigCommerce. - There are
somewhere between 500 to 1000 employees at BigCommerce. - Philip will be in the office May 3 – May
5.
<div className="hidden">**Do**</div>
<div>

- There are 500–1000 employees at BigCommerce.
- There are somewhere between 500 to 1000 employees at BigCommerce.
- Philip will be in the office May 3 – May 5.

</div>
</Dos>

**This is an em dash (—)**

Em dashes are used to indicate an abrupt pause or change in the middle of a sentence. Em dashes can also be used to call out or add emphasis to an important part of a sentence. Em dashes should always have a space before and after.

<Dos>
<div className="hidden">**Do**</div>- Wait, that’s not a hyphen — it’s an em dash. - I went
shopping — on a site powered by BigCommerce — and bought a new pair of jeans.
<div className="hidden">**Do**</div>
<div>

- Wait, that’s not a hyphen — it’s an em dash.
- I went shopping — on a site powered by BigCommerce — and bought a new pair of jeans.

</div>
</Dos>

### Percentages
@@ -216,22 +253,33 @@ Let’s look at an example:
</div>

<Dos>
<div className="hidden">**Do**</div>- Under “List your products on Google,” click “Get started.”
<div className="hidden">**Do**</div>
<div>

- Under “List your products on Google,” click “Get started.”

</div>
</Dos>

### Slashes

You can use forward slashes “/” to indicate the word “or” between two words. When doing so, don’t use spaces before or after the slash. Don’t use backlashes “\”.

<Dos>
<div className="hidden">**Do**</div>- if/when - and/or
<div className="hidden">**Do**</div>
<div>

- if/when
- and/or

</div>
</Dos>

On the other hand, when using a forward slash to signify “or” between two multi-word phrases, use spaces before and after the slash — it helps with readability.

<Dos>
<div className="hidden">**Do**</div>- Download the app from the Apple App Store / Google Play
Store.
<Dos hideHeader={true}>
<div className="hidden">**Do**</div>
<div>Download the app from the Apple App Store / Google Play Store</div>
</Dos>

### Units of measurement
@@ -240,12 +288,14 @@ Add a space between numbers and units of measurement. Use all lowercase and alwa

Don’t add a period. Don’t pluralize measurements (“lbs” is in common use and okay to use).

<Dos>
<div className="hidden">**Do**</div>- 75 lbs, 14 in, 7 cm
<Dos hideHeader={true}>
<div className="hidden">**Do**</div>
<div>75 lbs, 14 in, 7 cm</div>
</Dos>

When abbreviating units of data, always capitalize MB (megabyte) and GB (gigabyte). Don’t use Mb and Gb as these represent different units of measurement typically used when measuring Internet speeds.

<Dos>
<div className="hidden">**Do**</div>- 10 MB, 10 GB
<Dos hideHeader={true}>
<div className="hidden">**Do**</div>
<div>10 MB, 10 GB</div>
</Dos>