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."
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.
Link preferences
Linking to internal pages
When linking to another page on TON documentation, use the relative path over the absolute path.
Correct link:
Read more about [smart contracts](/v3/documentation/smart-contracts/overview/)
Incorrect link:
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.
Correct link:
Read more about [smart contracts](/v3/documentation/smart-contracts/overview/)
Incorrect link:
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.
Correct link:
Read more about [smart contracts](/v3/documentation/smart-contracts/overview/)
Incorrect link:
Read more about [smart contracts](/v3/documentation/smart-contracts/overview)