| title | slug | toc_max_heading_level |
|---|---|---|
Style Guide |
/style-guide |
2 |
This document defines the styles, word and term usage, and content formatting for Sui documentation. Entries are in alphabetical order. A style guide is never finished. Expect continued iterations to add additional styles, additional information to existing styles, and infrequently a change to an existing style.
Reference works for making content accessible:
- A11Y Style Guide
- Bitsofcode Accessibility Cheatsheet
- Atlassian Design System - Inclusive writing reference
- MailChimp's writing style guide
- Microsoft Style Guide Accessibility Terms
- Writing for All Abilities (Microsoft Style Guide)
Don't use color or special symbols to add emphasis to text. Screen readers are designed to interpret bold (<strong>) and italic (<em>) in web pages.
Add captions and alt text that describe the image for someone using a screen reader. What are the important details in the image that someone using a screen reader can't see?
Use alt text to describe what the image shows. Use the caption to explain why the image is meaningful in the context of the page.
An image is not a substitute for text; images should only supplement text. Do not rely on an image to convey information not in text form. For example, an image of a table of values does no one any good if the image fails to display for a host of possible reasons.
Spell out a term or phrase on first use in a topic, followed by the acronym in parentheses. Then use the acronym for subsequent mentions.
Example
You can mint non-fungible tokens (NFTs) using your Sui Wallet. To view an NFT after you mint it, click the NFTs tab of your wallet.
Alerts add emphasis to information. Use Admonitions, a Docusaurus feature, to indicate the alert is a Note, Tip, or Caution. The explanation in the alert must be a complete sentence and use sentence case.
Use Note to add emphasis to information that the reader should know, but could be overlooked when scanning a topic or document. Provide information that prevents users from getting stuck.
:::note
The system processes updates only once every 24 hours at UTC 00:00.
:::
:::note
The system processes updates only once every 24 hours at UTC 00:00.
:::
Use Tip to give the reader advice that might be helpful, such as a best practice.
:::tip
Change your home directory after installing the IDE.
:::
:::tip
Change your home directory after installing the IDE.
:::
Use Caution when the information could cause the user to lose data or to start over. If you instruct a user to delete something, warn them about what happens when they delete it.
:::caution
Backup your configuration files before you delete your network.
:::
:::caution
Backup your configuration files before you delete your network.
:::
Do:
Use sentence capitalization for section headings, table cells, list items, captions, alt text, and error messages.
Capitalize proper nouns. Proper nouns.
Always capitalize the first word of a new sentence, even when the word is normally lower case, such as Web3 vs web3.
Don't:
Don't use all uppercase for emphasis, use bold instead. (IMPORTANT vs Important)
Don't use bi-capitalization / internal capitalization unless it is part of a brand, such as YouTube or DreamWorks.
Don't capitalize the spelled-out form of an acronym unless it's a proper noun, such as HyperText Markup Language (HTML).
When words are joined by a slash, capitalize the word after the slash if the word before the slash is capitalized.
Example
Country/Region
Turn on the On/Off toggle.
For title capitalization, follow these guidelines:
- Don't capitalize a, an, and, but, for, in, or, so, to, with, yet , or other short conjunctions and prepositions unless it's the first or last word
- Capitalize all other words (including Is and Be as they are verbs)
- Capitalize the word after a hyphen
- Match casing for commands or special terms, such as cURL or dApp.
- Match the casing for API elements and programming language keywords
Use inline code in a sentence to refer to functions and other code pieces. Use codeblocks to show larger sections of a program. All code should be written exactly as it appears in a code editor, so that other people can copy and paste it from documentation directly into a code editor. Do not use images to show code.
Use backticks (`) around individual code within a sentence, which will format it as code in markdown. Do not use quotes, emphasis, or any other formatting to distinguish code from surrounding text.
The
display::new<T>call creates aDisplay.
The `display::new<T>` call creates a `Display`.
Use the text before a codeblock to describe what the codeblock does. Use text after the codeblock to point out particular elements in the code and how they work. Do not use codeblocks as a substitute for descriptive text. Codeblocks help readers understand descriptive text in the documentation.
Initiate a codeblock in markdown with three backticks (```).
Example
module sui::display {
/// Sets multiple fields at once
public fun add*multiple(
self: &mut Display,
keys: vector`<String>`,
values: vector`<String>`
) { /* ... \*/ }
Use Active voice whenever possible. Active voice is direct, clear, and uses fewer words. Passive voice is often less clear, awkward, and uses more words.
Example
Active: She installed the software.
Passive: The software was installed by her.
Use present tense verbs with the appropriate mood.
There are three grammatical moods:
- Indicative – used to deliver facts
- Imperative – used to provide directions
- Subjunctive – used to convey a wish or possibility
Use indicative verbs most of the time in conceptual content.
Use imperative verbs for tasks, procedures, and instructions.
Example
- Indicative – Sui network explorers display transactions on the network.
- Imperative – Open a Sui network explorer to view transactions on the network.
- Subjunctive – We suggest that you view your transaction in a Sui network explorer after you complete a transfer.
Use second person in most cases.
Example
You used to could view transaction history in Sui Explorer.
Rather than:
We used to could view transaction history in Sui Explorer.
Use present tense whenever possible. Use future tense (something will happen) only for events that occur on a future date, such as a product release or trade show.
Do not use future tense when describing a product, or providing guidance in tasks. From the user perspective, it is the present for them when they follow the steps in a task. Consider the example of saving a file.
Example present tense
Click Save to save the updated file.
When you click Save, your device writes the changes to disk.
To save a file after you modify it, click Save.
Example future tense
Your changes will be saved when you click Save.
While this is technically accurate, it separates the person from the object of the action. This makes it more difficult to parse the sentence for ESL speakers, and is harder to localize.
When you click Save, the file will be written to disk.
In this example, when will the file be written to disk? It happens immediately upon clicking Save. If you check the timestamp on the file, the time reflects the moment at which you clicked Save, not a time after that moment.
Do use serial commas.
Example
Rachael Ray finds inspiration in cooking, her family and her dog.
It is much more clear to use:
Rachael Ray finds inspiration in cooking, her family, and her dog.
Example
You must install Cargo, Rust, Docker, and the Sui CLI to create a Sui node.
Use descriptive titles that include keywords to help readers find the information. Use shorter titles in the navigation pane.
Use enough words in headings and titles to make it easy to know which link to click on a search results page. One word titles (Installing) do not provide enough information to determine the contents of a topic.
Users search for information to complete a specific task, so help them identify the topic that helps them by using descriptive titles. For example, Get Started. Get started with what? If there are multiple products or programs available it could be anything.
Get Started with Sui is better, but users want to get started with a specific task or user journey with Sui. Instead of Get Started with Sui, describe the specific task or journey, such as Create a Sui Full Node or Sui Validator Guide. Use Get Started as a heading on the Documentation landing page to categorize tasks for new users.
This is a Topic Title
## title: This is a Topic Title
Use sentence casing for section headers.
This is a section heading
## This is a section heading
Only use images and screenshots to supplement and help explain text. Images do not replace text. Readers should be able to understand the documentation without the images. However, images can help readers understand the text more clearly.
Use .png when possible, otherwise use .jpg
Images should be at least 400 pixels wide. If an image looks blurry when uploaded, try making a new image in higher resolution.
Use alt text to describe what the image shows. Use the caption to explain why the image is meaningful in the context of the page. See Accessibility considerations for captions.
You can create flowcharts and similar images directly in Markdown.
https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/
Use Snagit or other tools to capture screenshots.
Use a list for a series of items or steps instead of writing them as a sentence. Introduce the list with a description of the list elements ending in a colon (:).
Instead of:
The Build section of the documentation includes topics about: Building with Sui, Using the CLI to Start a Network, Creating Smart Contracts, Sui Tutorial, and Sui Examples.
Use:
The Build section of the documentation includes the following topics:
- Building with Sui
- Using the CLI to Start a Network
- Creating Smart Contracts
- Sui Tutorial
- Sui Examples
Use a numbered list when:
- the items in the list must be performed in a specific order, such as the steps in a task
- the items in the list describe a sequence of events, such as a workflow or scenario
- Create a fork of the repo.
- Clone your fork of the repo.
- Install Sui.
1. Create a fork of the repo.
1. Clone your fork of the repo.
1. Install Sui.
Use bulleted lists to list more than two pieces of related information, such as links or terms, that don't need to be in a specific order. Optionally, use a bulleted list for only two items to include a description of the items in the list. Use sentence capitalization in lists, and use punctuation consistently for all list items. Do not use an ending period unless the list item includes a full sentence.
Sui Explorer used to support the following browsers:
- Firefox version X or later
- Chrome version X or later
- Edge version X or later
Sui Explorer used to support the following browsers:
- Firefox version X or later
- Chrome version X or later
- Edge version X or later
Use a term list to define terms or concepts.
Term: A description of the term.
DAG: A directed acyclic graph (DAG) is a data modeling or structuring tool typically used in data architectures.
**Term:** A description of the term.
**DAG:** A directed acyclic graph (DAG) is a data modeling or structuring tool typically used in cryptocurrencies.
Use initial / sentence capitalization in list items.
- First list item
- Second list item
* First list item
* Second list item
- First list item
- Second list item
1. First list item
1. Second list item
Write out numbers less than 10
Example
The folder contains seven files.
Use digits for larger numbers.
Example
The folder contains 24 files.
In body text, use numbers consistently if using both numbers less than and greater than 10.
Example
One folder contains 7 files, and the other contains 24 files.
For ease of reading, use both words and numbers when you use two numbers for different things together.
Example
The folder contains twenty 12-page documents.
Don't start a sentence with a numeral. Instead, add a qualifier or spell out the number.
Example
At least 20 pieces of candy fell off the table.
Twenty pieces of candy melted.
Measurements should be written as numerals.
Example
The server processes 2 terabytes of data in 8 milliseconds.
Always use relative links when linking to topics on docs.sui.io.
Include the .mdx extension when creating internal links so that they also work from the source file in GitHub.
Use the topic title of the target topic as the link text for the link in a list or "Learn more" sentences. Do not use a URL as the link text.
To learn more, see Examples of Sui Smart Contracts.
To learn more, see [Examples of Sui Smart Contracts](/guides/developer/app-examples.mdx).
Use keywords from the target topic title when using links inline.
Before you install Sui, make sure to install the prerequisites.
Before you install Sui, make sure to install the [prerequisites](/guides/developer/getting-started/sui-install.mdx#prerequisites).
Introduce a procedure with an infinitive verb. Format procedures using a numbered or ordered list.
To get the latest version of the Sui Wallet extension:
- Open Google Chrome.
- Click Extensions, then click Manage Extensions.
- Click Details for the Sui Wallet extension, then click View in Chrome Web Store.
To get the latest version of the Sui Wallet extension:
1. Open Google Chrome.
1. Click **Extensions**, then click **Manage Extensions**.
1. Click **Details** for the Sui Wallet extension, then click **View in Chrome Web Store**.
When you provide instructions to press keyboard keys, such as Press Enter to continue, use uppercase for the key name and format the key name as bold text.
Capitalize proper nouns throughout.
Proper nouns include:
- Names of people (Bob Ross)
- Named places, such as a city (San Francisco) or a train station (Union Station)
- Products (Slack) and services (Google Play)
- Trademarks, such as Coca-Cola
- Book titles, such as The Move Book
- Standards or technologies, such as Local Area Network (LAN)
Example
Sui Wallet
Product names are proper nouns. Capitalize all words of a product name. When referring to a product, use only the product name without “the”. When referring specifically to a Sui wallet, use Sui Wallet or Ethos Wallet and not just wallet. Users likely have multiple wallets, and we want to make it clear which wallet. Use wallet generically when referring to the concept of a wallet.
Example
There are several types of wallets to choose from.
Never share the recovery passphrase for your wallet with anyone.
The Sui network supports the following wallets:
- Sui Wallet
- Ethos Wallet
- Coinbase Wallet
Example
Sui Wallet
Example
You can mint an NFT directly from your Sui Wallet.
Avoid using slashes in place of "and" or "or", such as True / False or True/False. Use True or False, or True | False in code documentation.
If you do use a slash, include a space between the term and slash.
When using fractions, use no spaces, for example 3/4.
Use US English spelling in source content.
Capitalize the first word in the heading. Center align the text. Bold labels in the Header row.
| Column one | Column two | Column three | Column four |
|---|---|---|---|
| Metric name | 10 | X | Text string. |
| **Column one** | **Column two** | **Column three** | **Column four** |
Center align labels in the Heading row. Left align strings of text. Center align values and Xs or checkmarks.
| Column one | Column two | Column three | Column four |
|---|---|---|---|
| Metric name | 10 | X | Text string. |
| **Column one** | **Column two** | **Column three** | **Column four** |
| :--- | :---: | :---: | :--- |
Follow style guidelines for regular body text.
Format UI elements, such as field labels, button names, and menu commands, in bold text. Always match the exact text or label of the UI element, including capitalization. Do not include special characters, such as ellipses, if included in the element label.
Example
To open a different file, click File > Open FIle.
Example
Click More Transactions to open the Transactions page.
Add text and create a link to a site or URL. Provide the URL only when a reader needs to copy it, such as in example code or configuration files.
Refer to pages in the documentation set as “topic”s. A “guide” can comprise many related topics.
Example
See the Install topic in the Validator guide for more information.
:::info
You can also just refer to a topic by title where it makes sense. See Installing Sui for more information.
:::
- Use simple words, concise sentences
- Don't use common words in new ways
- Use technical terms carefully
- Avoid jargon
Optionally use contractions to provide a more conversational tone. It's OK to use them inconsistently. Be mindful that they can be confusing to non-native speakers.
Describe the section.
Describe the additional entry.
Indented example for the section. (Normal text, indented)
Indented example for the section. (Roboto Mono Light)
- Write the Docs Style Guide article
- GitLab Style Guide - managed as a community project
- Digital Ocean Style Guide
- SUSE Style Guide
- Microsoft Style Guide
- Google Developer Style Guide
- CDN Language and Style Reference