Skip to main content

Content standardization

Introduction​

This guideline aims to maintain a consistent documentation style and help contributors standardize their content so that it seamlessly integrates into the documentation.

Text preferences​

Use American English​

For words that have multiple spellings, use American English over British English.

Examples:

  • "decentralized" over "decentralised"
  • "color" over "colour"
  • "analyze" over "analyse"

Use active voice​

Sentences using active voice are more concise and efficient, making your writing more engaging and easier to comprehend.

Active voice sentence: An actor acts on a target

"The smart contract processed a message."

Passive voice sentence: A target acts on an actor

"The message was processed by the smart contract."

Read more on active voice

This isn't an easy one, especially for non-native English speakers. If you aren't sure, don't worry. We'll help with any of these.

Grammar​

This documentation uses cspell to correct grammar during development.

The cspell will check the spelling and automatically suggest corrections in case of mistakes before creating a new commit. Feel free to add specific words to the cspell.json config and include them in the verification dictionary.

Date format​

Use the "Mon D, YYYY" format. This approach is standard for American readers, spells out the month (or uses a three-letter abbreviation), and minimizes confusion with day–month ordering.

Preferred format:​

  • Nov 2, 2023
  • Feb 11, 2023

Incorrect format:​

  • 2-Nov-2023
  • 11/2/2023
  • 2/11/2023

Adhering to these guidelines creates a unified approach to presenting dates, fostering clarity and comprehension throughout the TON documentation.

Linking to internal pages​

When linking to another page on TON documentation, use the relative path over the absolute path.

Read more about [smart contracts](/v3/documentation/smart-contracts/overview/)
Read more about [smart contracts](https://docs.ton.org/v3/documentation/smart-contracts/overview)

Don't hard-code the language path (for example, /mandarin/) in any links. This maintains consistent capability across different language versions of the site.

Read more about [smart contracts](/v3/documentation/smart-contracts/overview/)
Read more about [smart contracts](/mandarin/v3/documentation/smart-contracts/overview)

Set a trailing slash to all links. This approach keeps links consistent and avoids redirects, which hurts site performance.

Read more about [smart contracts](/v3/documentation/smart-contracts/overview/)
Read more about [smart contracts](/v3/documentation/smart-contracts/overview)

Include related resources on your page in an H2 section titled ## See also.

This section guides readers to additional materials and supports a cohesive developer journey.

Example:​

## See also

- [Style guide](/v3/contribute/style-guide/)
- [Typography](/v3/contribute/typography/)
- [Localization program](/v3/contribute/localization-program/overview/)

Image preferences​

Linking to images​

When adding an image to a page, download and set an image in the TON documentation static/img folder.

Correct linking:​

![jetton_transfer](/img/docs/asset-processing/jetton_transfer.png)

Incorrect linking:​

![tact_logo](https://docs.tact-lang.org/_astro/logomark-dark.BSmgZYWc_ZKRrUl.svg)

This is helpful to ensure the image will be available.

Light and dark theme modes​

TON documentation supports theme-specific images. Follow these steps to add themed pictures to the page.

  1. Themed mode is available only for .mdx files.

  2. Import the ThemedImage module in the header.

import ThemedImage from '@theme/ThemedImage';
  1. Set the links for both images according to the example:
<br></br>
<ThemedImage
  alt=""
  sources={{
    light: '/img/docs/message-delivery/message_delivery_2.svg?raw=true',
    dark: '/img/docs/message-delivery/message_delivery_2_dark.svg?raw=true',
  }}
/>
<br></br>

Annotation specification​

To depict message processing, use a graphical representation that resembles a smart contract graph, including labels for transactions and messages.

If the transaction order isn't essential, omit their labels. This approach simplifies the diagram, making it easier to read and understand the message and contract details.

Annotation primitives​


  • Avoid using a large variety of bright colors.
  • Modify figures by applying techniques such as a dashed border.
  • To emphasize specific details, display transactions using distinct line styles (e.g., solid and dashed).

Message processing schemes​

On the TON blockchain, providing clear explanations of actor behavior and message processing for various smart contracts and fundamental scenarios is essential.

The message processing schemes offer additional context for readers seeking a clear understanding of actor behavior. These schemes should be unified throughout the TON documentation to ensure maximum clarity.

Example​



Sequence diagram​

Use a sequence diagram for complex and repetitive communication schemes between 2-3 actors. For messages, use the notation of a typical synchronous message arrow.

Example​



Scheme formats and colors​

Format:​

  • Use a PNG format for the diagrams in the documentation to ensure readability on various devices.

Fonts:​

  • Use the Inter font family for all text within diagrams.
  • Maintain a consistent text size.
  • Avoid overusing bold and italic formatting for optimal readability.

Themed colors for light mode:​

  • Pencil Hand Drawn, default Visio theme.

Themed colors for dark mode:​

  • Font #e3e3e3.
  • Background #232328.
  • Light Highlight, arrows and scheme borders #058dd2.
  • Dark Highlight, arrows and scheme borders #0088cc.
  • InnerBackGround, for nested blocks #333337.

Version control policy:​

  • Store the original files in the project's Git repository under the /static/visio directory to facilitate future modifications.
  • Learn Visio references directly from Visio sources.

Terminology​

TON​

TON should always be capitalized.

Correct usage:

  • TON

TON with a word​

  • It is essential to ensure the correct use of THE in the TON documentation. TON Blockchain and TON Ecosystem are capitalized terms, and therefore, do not require THE in their usage.
  • We write TON with regular nouns, and if it requires THE according to English grammar, we use it. For instance: "The TON Connect protocol is a..."

Correct usage:

  • TON Blockchain
  • TON Ecosystem
  • The TON Connect protocol

TON Center​

Correct usage:

  • TON Center

Incorrect usage:

  • Toncenter
  • TonCenter
  • TONcenter

Mainnet​

When referring to the TON Mainnet (i.e. not referring to a Testnet) use the proper noun. Proper nouns help avoid confusion and build greater understanding.

Correct usage:

  • Mainnet
  • TON Mainnet

Incorrect usage:

  • main net
  • mainnet
  • Main net
  • TON mainnet

AccountChain​

Correct usage:

  • AccountChain

Incorrect usage:

  • Account Chain
  • Accountchain

WorkChain​

Correct usage:

  • WorkChain

Incorrect usage:

  • Workchain

ShardChain​

Correct usage:

  • ShardChain

Incorrect usage:

  • Shardchain
  • Shard Chain

WorkChain​

Correct usage:

  • WorkChain

Incorrect usage:

  • Workchain
  • Work Chain

MasterChain​

Correct usage:

  • MasterChain

Incorrect usage:

  • Masterchain
  • Work Chain

Proof-of-work / Proof-of-stake​

Proof-of-work should be capitalized only when at the beginning of a sentence. In any other instance, all letters should be lowercase. In either case, proof-of-work should be hyphenated between each word.

Correct usage:

  • Proof-of-work
  • proof-of-work
  • Proof-of-stake
  • proof-of-stake

Incorrect usage:

  • Proof-of-Stake
  • Proof of stake
  • proof of stake

The same rules we apply to proof-of-work apply to proof-of-stake, proof-of-authority, proof-of-humanity, proof-of-individuality, etc.

Smart contract​

The smart contract is a common noun and should only be capitalized at the beginning of a sentence. In any other instance, all letters should be lowercase.

Correct usage:

  • Smart contract
  • smart contract

** Incorrect usage:**

  • Smart Contract

Zero-knowledge​

Zero-knowledge is a common noun and should only be capitalized at the beginning of a sentence. In any other instance, all letters should be lowercase. In either case, zero-knowledge should be hyphenated between each word.

Correct usage:

  • Zero-knowledge
  • zero-knowledge

Incorrect usage:

  • Zero-Knowledge
  • Zero knowledge
  • zero knowledge

ZK-proof​

When using the abbreviated form of zero-knowledge proof you should shorten zero-knowledge to ZK, and hyphenate the abbreviation.

Correct usage:

  • ZK-proof

Incorrect usage:

  • Zk-proof
  • zK-proof
  • zk-proof
  • Zk proof
  • zK proof
  • zk proof

ZK-rollup​

When using the abbreviated form of zero-knowledge rollup you should shorten zero-knowledge to ZK, and hyphenate the abbreviation.

Correct usage:

  • ZK-rollup

Incorrect usage:

  • Zk-rollup
  • zK-rollup
  • zk-rollup
  • Zk rollup
  • zK rollup
  • zk rollup

Article authors​

When citing articles by a specific author or organization, use the article's name as a link, followed by a dash and the author's name italicized.

Correct description:​

- [How to shard your TON smart contract and why](https://blog.ton.org/how-to-shard-your-ton-smart-contract-and-why-studying-the-anatomy-of-tons-jettons) — _Tal Kol_
- [TON Teleport BTC Whitepaper](https://tgbtc.gitbook.io/docs/whitepaper/abstract) – _RSquad Blockchain Lab_

Incorrect description:​

- [How to shard your TON smart contract and why](https://blog.ton.org/how-to-shard-your-ton-smart-contract-and-why-studying-the-anatomy-of-tons-jettons)
- [TON Teleport BTC Whitepaper](https://tgbtc.gitbook.io/docs/whitepaper/abstract) by RSquad Blockchain Lab

See also​