# TON documentation style guide (https://docs-op93jxul6-ton-core-docs.vercel.app/llms/contribute/style-guide-extended/content.md)
## Purpose, scope, and normative terms [#0-purpose-scope-and-normative-terms] Purpose. This guide defines the required writing style for all public, developer-facing TON documentation. Its goal is to maximize reading experience and task success: a developer should be able to land on the right page, follow it once, and succeed. This document is intentionally explicit so both humans and automated tools (including LLM reviewers) can apply it consistently. (Why: a single, explicit house style reduces cognitive load, prevents voice drift, and enables reliable human and automated review.) Scope. These rules **MUST** be followed on all pages in the docs site, including, for example: step-by-step/how-tos, explanations, and references (CLI, TVM, standard contracts, network, config, serialization). Exceptions **MUST** be documented in Style exceptions with owner and expiry. (Why: consistent coverage avoids fragmented micro-styles; documented exceptions stay accountable and temporary.) Normative terms. The keywords **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, **MAY**, **RECOMMENDED**, and **OPTIONAL** are to be interpreted as described in RFC 2119/8174. (Why: shared semantics eliminate ambiguity about what is mandatory vs. optional.) Definitions (used throughout). * Page — a single documentation article. * Doc type — one of: Step by step, How-to guide, Explanation, Reference (see [§3](#3-documentation-framework-content-types)). * Snippet — any code or command block. * Partial snippet — a focused excerpt that **MAY** be non-runnable by itself and **MUST** be labeled as such (see [§10](#10-code-and-command-examples)). * Placeholder — a value the reader must replace; formatted as ``. * Admonition — a callout such as Note, Tip, Important, Caution, or Warning. * Reference anchor — a deep link to a specific item in a reference page (flag, field, error code, and similar items). Out of scope. Editorial process, CI wiring, analytics/metrics, and governance live outside this guide. (This guide is about writing.) (Why: focusing on writing rules keeps this document stable and avoids process churn.) Living document. This guide evolves with the documentation. Editors **MAY** update rules as the information architecture and best practices change. When the guide changes, all existing documentation **MUST** be re-validated against the new rules and updated as needed to keep the docs consistent. (Why: styles must adapt as the product and the information architecture evolve; re-validation prevents long-term drift.) ### Severity model (release-blocking) [#severity-model-release-blocking] Legend. \[HIGH] blocks release; \[MEDIUM] warns (non-blocking); \[LOW] suggestion. Defaults. Unless marked otherwise: MUST/MUST NOT → \[MEDIUM]; SHOULD/SHOULD NOT → \[LOW]; MAY/OPTIONAL/RECOMMENDED → \[LOW]. Global overrides (always \[HIGH]). Safety callouts ([§11](#11-safety-critical-content-blockchain-specific)) when required; secrets in examples; copy/paste hazards (prompts in commands, mixed command+output, hard-wrapped commands, undefined placeholders); destructive flags without warnings; broken/missing anchors or linking to superseded pages as normative; non-HTTPS/tracked/unofficial links when official exists; use of `{}`/`[]` placeholders in commands; silent truncation of IDs/addresses. Annotation scope. To keep the doc clean, inline badges are added only to \[HIGH] items; all other items inherit the defaults above.
## Goals and principles (reader-first, answer-first) [#1-goals-and-principles-reader-first-answer-first] * Intent. Every page exists to help a developer finish a real task quickly and correctly. * Pages **MUST** optimize for clarity, scannability, accuracy, and trust; * Pages **MUST NOT** contain marketing language in technical sections. \[HIGH] * Pages **SHOULD** be answer-first (solution before theory) and example-first (real code before exposition). (Why: task-focused, plain, and scannable pages help readers complete work on the first try; marketing copy and theory up front slow readers and reduce trust.) Principles. 1. Answer-first. Open with purpose, outcome, and prerequisites. Then show the steps (or the API signature in reference). Background theory moves to its own Explanation page or a brief end section. (Why: leading with the solution shortens time-to-success; moving theory prevents detours for readers who just need to act.) Example (good): Goal: “Send a jetton from a web app.” Prerequisites: JS SDK, funded testnet wallet. Steps: 1–5. Verify: expected output. Troubleshoot: common errors. 2. Example-first and precise. Provide copy-pasteable snippets with expected output. Use `` values and define them at first use. Avoid unnecessary narrative around code. (Why: runnable, minimal examples remove guesswork; placeholders prevent users from pasting unsafe, hard-coded values.) 3. Minimal concepts in task pages. Do not front-load long explanations in step-by-step/how-tos. Link to a concept page instead. (Why: keeping theory separate avoids cognitive overload; readers can pull background only if they need it.) 4. Single source of truth. Don’t duplicate reference tables in guides. Summarize only what's needed, then link to the reference anchor. (Why: duplication drifts and conflicts; deep links keep guides brief and ensure details stay correct in one place.) 5. Scannability. Prefer short paragraphs (≤ \~5 sentences) and short sentences (\~15–20 words). Use headings, lists, and tables to chunk information. See [§8](#8-readability-and-scannability) for norms and flexibility. (Why: short, well-chunked text is faster to scan and reduces rereads and errors.) Anti-patterns (MUST NOT). Vague claims (“blazingly fast”), filler (“simply”, “just”, “obviously”, “please note”), and long theoretical detours in task pages. (Why: vague or padded text wastes time and hides the action; front-loaded theory blocks progress for users who came to do a task.)
## Audience and assumptions [#2-audience-and-assumptions] Default audience. The primary reader is new to blockchain but experienced in software development. (Why: sets a clear baseline so pages explain TON concepts without re-teaching general programming.) Pages **MUST NOT** re-teach generic developer skills (e.g., basic shell, Git, Python/JS syntax) unless a step is unusual for TON. (Why: keeps pages focused and shorter; duplicating generic skills adds noise and goes stale quickly.) Declaring prerequisites. Step by step and how-to pages **SHOULD** include a Prerequisites block at the top. Reference pages **SHOULD** include a one-line Summary to orient the reader. (Why: consistent placement improves scanning and lets readers self-select quickly.) ### 2.1 What belongs in Prerequisites [#21-what-belongs-in-prerequisites] Prerequisites are entry conditions: things the reader must have or have done before starting. Each item **MUST** be concrete and verifiable. (Why: readers should be able to check each prerequisite before starting to avoid wasted effort.) Examples of valid prerequisite categories: * **Software already installed** (not installed during the guide). Specify version and link to download page. * **Accounts or access already obtained**: API keys, RPC endpoints, wallet accounts. * **Artifacts from prior work**: `"A deployed contract from [Deploy a counter](https://docs-op93jxul6-ton-core-docs.vercel.app/llms/path/to/guide/content.md)"`, `"A funded testnet wallet"`. * **Funds or tokens**: "Testnet TON from the [faucet](https://...)". * **Unusual hardware** (only when relevant): "A machine with at least 16 GiB RAM". ### 2.2 What does not belong in Prerequisites [#22-what-does-not-belong-in-prerequisites] * **Obvious assumptions**. You **MUST NOT** list: internet connection, an operating system, a keyboard, a terminal/shell, a browser, a text editor, or similar universal tools. (Why: obvious items waste space and insult reader intelligence.) \[HIGH] * **Things installed or created during the guide**. If step 1 is "Install the SDK", the SDK is **NOT** a prerequisite — the prerequisite is what is needed to install it (e.g., Node.js). You **MUST NOT** list items that the guide itself provides. (Why: listing in-guide installations as prerequisites confuses readers about what they need beforehand.) \[HIGH] * **Skills or knowledge**. "Familiarity with TypeScript" or "Understanding of smart contracts" are audience statements, not prerequisites. Use a separate "Audience" note for these (e.g., "Audience: Intermediate. Assumes working knowledge of TypeScript and async/await."). You **MUST NOT** mix skills into the Prerequisites list. (Why: skills cannot be "installed" or verified the same way; separating them clarifies what readers need to do vs. know.) \[HIGH] * **Background reading or concept links**. `"Read the [Account model](https://docs-op93jxul6-ton-core-docs.vercel.app/llms/foundations/accounts/content.md) page first"` belongs in prose or a "Background" section, not Prerequisites. If understanding a concept is truly required, state it as an audience assumption. You **SHOULD NOT** put learning links in Prerequisites. (Why: prerequisites are for artifacts and tools, not reading assignments.) ### 2.3 Version specifications [#23-version-specifications] * Software prerequisites **MUST** specify at least the version tested in the guide. (Why: unversioned requirements cause "works on my machine" failures.) \[HIGH] * Software prerequisites **SHOULD** specify a supported range when known (e.g., "Node.js 20 or later LTS", "Python 3.10+"). (Why: ranges tell readers whether their existing installation works.) * You **MUST NOT** use vague terms like "latest" or "recent version". (Why: "latest" changes over time and provides no actionable information.) \[HIGH] ### 2.4 Links in Prerequisites [#24-links-in-prerequisites] * Each software prerequisite **MUST** link to an official download or installation page, not to the project homepage or documentation root. (Why: readers need to act, not browse; download pages are actionable.) \[HIGH] * For tools with OS-specific installers, you **MAY** link to a general downloads page that offers all variants. * For TON-ecosystem tools documented in these docs, link to the internal installation guide if one exists. ### 2.5 Prerequisite examples [#25-prerequisite-examples] Good: ```text Prerequisites: - [Node.js](https://nodejs.org/en/download/) 20 or later LTS - A funded testnet wallet (get testnet TON from the [faucet](https://t.me/testgiver_ton_bot)) - An RPC endpoint — use a public endpoint or get one from [TON Center](https://toncenter.com/) ``` Bad: ```text Prerequisites: - A computer with internet access ← obvious - Node.js ← no version, no link - Install the TON SDK ← installed in the guide, not a prerequisite - Familiarity with JavaScript ← skill, not a prerequisite - Read the [wallets overview](https://docs-op93jxul6-ton-core-docs.vercel.app/llms/wallets/content.md) ← background reading, not a prerequisite ``` ### 2.6 Audience and skill assumptions [#26-audience-and-skill-assumptions] Pages with advanced requirements **MUST** state them at the top in a separate Audience note, not in Prerequisites. (Why: separating "what you need to have" from "what you need to know" helps readers self-select.) Example: ```text Audience: Advanced. Assumes understanding of TVM exit codes and TL-B schemas. See: [TVM exit codes](https://docs-op93jxul6-ton-core-docs.vercel.app/llms/tvm/exit-codes/content.md), [TL-B overview](https://docs-op93jxul6-ton-core-docs.vercel.app/llms/data-formats/tlb/content.md). ``` Inclusive/global readers. Use plain, international English; avoid idioms and culture-specific references. Prefer neutral, inclusive terms (e.g., allowlist/denylist). (Why: idioms and local metaphors confuse non-native readers; inclusive terms are more precise and avoid unintended exclusion.)
## Documentation framework (content types) [#3-documentation-framework-content-types] Rule. Each page **MUST** be one of the following: Step by step, How-to guide, Explanation, or Reference. Types **MUST NOT** be mixed on a single page. The chosen type **MUST** be clear from the title and content. (Why: single-purpose pages are easier to find and follow; mixing types blurs intent and causes duplication.) Small, clearly marked asides (e.g., a 1–2-step “Verify” box in an Explanation) **MAY** appear when they aid comprehension; the page’s primary type remains unchanged. (Why: tiny, labeled asides help understanding without turning a concept page into a task page.) ### 3.1 What each type means (and looks like) [#31-what-each-type-means-and-looks-like] * Step by step (first success). Single happy path for newcomers. Hand-holding is **RECOMMENDED**. (Why: one clear path gets novices to a working result quickly; branching early increases drop-off.) Title style: “Deploy a counter contract on testnet”. (Why: action-oriented titles set expectations and help search/TOC scanning.) Sections (suggested): Objective → Prerequisites → Steps → Verify → Troubleshoot → Next steps. Keep Next steps minimal (1–3 essential links) or omit when the path is linear. **SHOULD** avoid theory beyond two short bullets; link to an Explanation page. (Why: predictable structure reduces cognitive load; keeping theory brief prevents blocking progress.) * How-to guide (goal-oriented procedure). A recipe to achieve a specific outcome. **MUST** be procedural and concise. (Why: readers come for a recipe; extra narrative slows execution and invites errors.) Title style: “How to mint a jetton with the CLI”. (Why: the “How to …” pattern matches search intent and signals page type while staying specific.) Rule: **MUST NOT** embed long background; link to concepts as needed. (Why: avoids duplication and keeps the guide focused; background stays current in one canonical place.) * Explanation (concepts/why). Background, architecture, trade-offs. **SHOULD** avoid step lists and commands. (Why: separating “why” from “how” improves comprehension and prevents pages from doing two jobs badly.) Title style: “Account model and messages in TON”. (Why: noun-based titles signal conceptual content and improve browseability.) * Reference (complete, factual). Exhaustive specs for APIs/CLI/SDK/types/errors. Non-narrative tables and exact semantics. (Why: factual, uniform entries are scannable and machine-linkable; narrative slows lookups.) Title style: “`tvm.runvm` — interface and exit codes”. (Why: placing the exact identifier in the title improves search and deep linking.) Rule: **MUST** be precise, consistent, and anchor-linkable. (Why: deep anchors let guides link directly; precision prevents support churn and conflicting copies.)
## Voice and tone [#4-voice-and-tone] Objective. Sound like a helpful expert: professional, precise, and approachable. Use the same voice across all pages. (Why: a consistent, expert tone builds trust and reduces cognitive load; readers know what to expect across the site.) Rules (binding). * Use present tense, active voice, and the imperative mood. Write steps as commands (e.g., “Run the validator.”), not future tense or passive voice. Avoid addressing the reader with “you”. (Why: imperative, active phrasing makes the action clear without personal address and reduces ambiguity in steps.) * Be neutral and inclusive. Avoid slang, idioms, culture-specific jokes, or hype. (Why: neutral language is easier for non-native readers and translators, and avoids alienating parts of the audience.) * **MUST NOT** use filler or patronizing words: simply, just, obviously, clearly, please note. Replace with exact instructions (Why: filler wastes time and can sound condescending; precise verbs tell the reader exactly what to do.) * Emojis in prose and headings **MUST NOT** appear. Use clear text or an `` when emphasis is needed. (Why: emojis are ambiguous, distract from procedures, and do not localize reliably.) * Emojis in code/command blocks **MAY** appear only when they are part of runnable code or a literal command/output string. Do not add emojis for decoration; the snippet **MUST** remain copy-pasteable and executable as shown. If quoting a UI/log message that contains an emoji, keep it verbatim inside quotes. (Why: runnable examples take precedence; avoiding decorative emojis preserves clarity and execution.) * Emojis in compact tables **MAY** be used sparingly as visual indicators only when they follow a widely understood convention (for example, `✅` / `❌` for supported/not supported, or `★` to mark a recommended option) and **MUST** be paired with a text label in the same cell or a descriptive header (e.g., “Supported — Yes/No”). Do not rely on an emoji alone to convey meaning, and **MUST NOT** use decorative or non-standard pictograms (for example, a play triangle to indicate videos). (Why: paired, conventional icons preserve clarity for screen readers, localization, and cases where emojis don’t render.) * Even where emojis are technically allowed (code/output or compact tables), they **SHOULD** be rare and **MUST** have a clear purpose. If the same meaning is clear without the emoji, remove it. (Why: conventional text remains clearer for global readers and translators.) * Use plain terms over legalese/Latinisms. “Use” not “utilize”; “before” not “prior to.” (Why: common words improve comprehension and reduce rereads; they are also translated more consistently.) * Avoid first-person pronouns (“we”, “I”, “our”). When an organization, product, or service is the actor, use its proper name (e.g., “Tonkeeper”, “TON”) or a neutral noun (“the node”, “the SDK”). Prefer imperative instructions without “you”. See [§5.8](#5-8-dont-get-personal) and [§5.10](#5-10-pronouns-and-person-references). (Why: neutral, explicit actors read cleanly and translate reliably.) Marketing and promotional language (ban). * You **MUST NOT** use marketing-style language anywhere in technical content, including titles, headings, steps, tables, references, and callouts. This includes: \[HIGH] * Superlatives and hype: "blazingly fast", "revolutionary", "world-class", "seamless", "best-in-class", "powerful", "cutting-edge". * Vague positive adjectives: "reliable", "robust", "essential", "elegant", "intuitive", "flexible", "comprehensive", "scalable" (when used without measurable criteria). * Dramatic or emotional framing: "elusive", "challenging", "painful", "frustrating", "nightmare", "perfectly", "beautifully". Technical writing states facts, not feelings. * Intensity words that exaggerate: "instantly", "immediately" (unless literally true), "extremely", "incredibly", "massive", "huge" (for non-quantified values). * Storytelling openers: "Imagine…", "Picture this…", "Have you ever…", "What if…". Start with the task or fact instead. (Why: hype and drama erode trust, slow scanning, obscure required actions, and age poorly.) * Replace subjective claims with measurable facts (numbers, constraints, conditions) or remove them entirely. If a claim cannot be tested or measured, delete it. (Why: facts enable correct implementation and reproducible results.) \[HIGH] * When describing benefits, state **what** happens and **under what conditions**, not how it feels. (Why: readers need actionable information, not emotional appeals.) * Bad: "This approach provides a robust and reliable solution." * Good: "This approach retries failed requests up to three times with exponential backoff." * Bad: "Tests catch issues instantly." * Good: "Tests run in under 2 seconds and fail on the first assertion violation." Micro-examples. * Bad: “We’ll just quickly configure the node; it’s super easy!” Good: “Configure the node.” * Bad: “Let’s go ahead and utilize the script.” Good: “Run the script.” * Bad: “Obviously, the transaction fails if the fee is low.” Good: “The transaction fails if the fee is too low.”
## Grammar and usage [#5-grammar-and-usage] Objective. Make sentences easy to parse on first read. (Why: clear, low-friction sentences reduce rereads and mistakes during implementation.) ### 5.1 Voice, tense, and person [#51-voice-tense-and-person] * You **MUST** use active voice by default. Passive voice **MAY** be used only when the actor is unknown or irrelevant. (Why: active voice makes who does what explicit; passive hides responsibility and confuses steps.) * Good: “The validator stops if the config is invalid.” * Bad: “The validator is stopped if the config is invalid.” * You **MUST** use the present tense for general behavior and instructions; the future tense **SHOULD** be reserved for time-dependent statements. (Why: present tense reads simpler and matches how-to steps; future tense adds unnecessary words and ambiguity.) * Good: “The API returns JSON.” * Bad: “The API will return JSON.” * Prefer imperative instructions without addressing the reader (“you”). Avoid first-person pronouns (“we”, “I”, “our”); when an organization, product, or service is the actor, use its proper name (e.g., “TON Center”, “TON”). See [§5.8](#5-8-dont-get-personal) and [§5.10](#5-10-pronouns-and-person-references). (Why: imperative, neutral phrasing keeps actors clear without personal address.) ### 5.2 Plain, precise wording [#52-plain-precise-wording] * You **SHOULD** prefer common words over legalese or Latinisms. (Why: familiar words are understood faster and translated more reliably.) * Use “use,” not “utilize.” Use “before,” not “prior to.” * Hedging and filler **MUST NOT** appear: simply, just, obviously, clearly, please note. Replace with exact actions or facts. (Why: filler wastes time and can sound condescending; specifics tell readers exactly what to do.) ### 5.3 Acronyms and terms [#53-acronyms-and-terms] * On first mention, you **MUST** spell out the term and follow with the acronym in parentheses. Use the acronym thereafter. (Why: defines terms once and keeps later text concise.) * Example: “The Open Network (TON)…” * Project terminology **MUST** follow the term bank/glossary (see [§13](#13-terminology-and-naming)). Avoid introducing synonyms for the same concept. (Why: one canonical term prevents confusion and search/indexing issues.) ### 5.4 Audience calibration [#54-audience-calibration] * Assume developers are new to blockchain (but experienced in software). **MUST NOT** re-teach generic developer skills unless a TON-specific nuance requires it (see [§2](#2-audience-and-assumptions)). Provide concise prerequisites when needed. (Why: focusing on TON reduces noise and keeps pages shorter and more relevant.) ### 5.5 Global and inclusive language [#55-global-and-inclusive-language] * You **MUST** avoid idioms, cultural references, and biased terms. Prefer neutral alternatives (e.g., allowlist/denylist). Use people-neutral wording and accessible examples. (Why: idioms and bias exclude readers and harm translation; neutral wording is clearer for everyone.) ### 5.6 Spelling and contractions [#56-spelling-and-contractions] * Spelling **MUST** follow American English (e.g., color, analyze). (Why: a single spelling standard prevents mixed variants and review churn.) * Contractions (don’t, can’t) **MAY** be used when they improve flow and do not reduce clarity. (Why: natural phrasing is easier to read as long as the meaning stays clear.) ### 5.7 Avoid unfinished work [#57-avoid-unfinished-work] Articles **MUST NOT** have any TODO, mentions of the work on the article to be done in future, itemized or text plans on its continuation, unfinished sections (headers without any text afterwards). The only exception is use of the `` component to tell the whole page is not finished yet. \[HIGH] ### 5.8 Don't get personal [#58-dont-get-personal] Articles **MUST NOT** use pronouns "you", "your" to refer to a reader, and **MUST NOT** use pronouns "we", "I", "our" to refer to an author. (Why: documentation must only describe facts; it knows no facts about readers; most facts about writers are off-topic). \[HIGH] ### 5.9 Avoid tautology, pleonasm, throat-clearing, and circular references [#59-avoid-tautology-pleonasm-throat-clearing-and-circular-references] Objective. Remove wordy redundancies and self-referential boilerplate so the reader gets the signal only. (Why: cutting redundancy speeds reading and reduces confusion.) #### Rules (normative) [#rules-normative] * You **MUST** remove tautologies/pleonasms (duplicate meaning in different words). (Why: redundant pairs add length without adding meaning.) * Bad: “End result” → Good: “result” * Bad: “Advance planning” → Good: “planning” * Bad: “Free gift” → Good: “gift” * You **MUST NOT** use throat-clearing/circular openers that describe the doc instead of delivering value. (Why: readers come to act; meta-introductions delay the task.) \[HIGH] * Bad: “In this section, we will discuss how to…”, “This document aims to explain…” * Good: “Deploy a validator on testnet.” (start with the action) * You **SHOULD** collapse wordy boilerplate into precise verbs. (Why: shorter, direct phrasing is faster to parse.) * Bad: “In order to” → Good: “To” * Bad: “For the purpose of” → Good: “To” * Bad: “Due to the fact that” → Good: “Because” * You **MUST** avoid doublets/triplets (pairs that mean the same thing). (Why: repeating the same idea signals uncertainty and wastes space.) * Bad: “each and every”, “basic fundamentals”, “final outcome”, “past history”, “future plans going forward”, “merge together”, “close proximity”, “completely eliminate” * You **MUST** avoid tautological logic and circular definitions. (Why: circular text doesn’t explain behavior and blocks understanding.) * Bad: “A jetton is a jetton if it conforms to the jetton standard.” * Good: “A jetton is a fungible token on TON defined by the Jetton standard, which specifies message formats for mint/transfer/burn.” * You **SHOULD** replace hedges and intensifiers with facts. (Why: intensity words add emotion, not information; facts reduce ambiguity.) \[HIGH] * Avoid: “basically”, “essentially”, “really”, “very”, “actually”, “literally” (unless literal). * If precision matters, give a number, constraint, or example instead. * You **MUST NOT** use and/or. (Why: it is ambiguous; readers cannot tell if both are allowed or required.) * Write: “A, B, or both” or “A or B” (choose one). * You **SHOULD NOT** use etc. in procedures or lists. (Why: open-ended lists leave readers unsure what is required.) * Either complete the list or write “for example” and stop. * You **MUST** avoid “as mentioned above/below”; link to the exact anchor instead (see [§12](#12-links-and-cross-references)). (Why: relative references break when pages change; links stay accurate.) * You **SHOULD** simplify “whether or not” → “whether”; “the reason is because” → “because”; “not uncommon” → “common/often.” (Why: simpler forms are clearer and shorter.) See also: [Appendix B](#b-banned-and-preferred-terms) lists additional banned intensifiers and tone words. #### Before/after micro-examples [#beforeafter-micro-examples] * Throat-clearing * Before: “In this guide, we will show you how to configure a validator.” * After: “Configure a validator.” * Tautology * Before: “The final outcome of the deployment process…” * After: “The result of the deployment…” * Wordy boilerplate * Before: “In order to reduce fees, you need to…” * After: “To reduce fees, …” * Hedge + intensifier * Before: “It’s basically very important to verify the address.” * After: “Verify the address.” * Circular reference * Before: “Sharding improves scalability because it shards the chain.” * After: “Sharding splits the chain into parallel shards that process transactions concurrently, increasing throughput.” ### 5.10 Pronouns and person references [#510-pronouns-and-person-references] * You **MUST** use gender-neutral singular “they/them/their” when referring to an unspecified or generic person. **MUST NOT** use gendered or split forms such as “he”, “she”, “he/she”, “s/he”, or “(s)he” for generic subjects. \[HIGH] (Why: singular “they” is inclusive, concise, and avoids awkward constructions.) * Prefer imperative instructions or role nouns to avoid pronouns when possible (e.g., “Deploy the contract.” or “The operator updates the config.”). (Why: direct phrasing is clearer and reduces ambiguity.) * When referring to a named individual who has stated pronouns, use that person’s pronouns; if unknown or irrelevant, default to “they”. (Why: respect individuals while keeping language inclusive.) * Do **NOT** anthropomorphize software or networks with gendered pronouns. Use neutral nouns or “it” (e.g., “the node restarts”, “it fails to start”). (Why: avoids confusion and maintains technical tone.) * For organizations, products, and services, use the proper name (e.g., “TON”, “Tonkeeper”) or the neutral “it”; do not use “we/I/our” in documentation. (Why: consistent, neutral references read cleanly and translate reliably.) ### 5.11 Parentheses [#511-parentheses] * Parentheses **MAY** be used for short clarifications and abbreviation expansions (for example, “The Open Network (TON)”) but **SHOULD NOT** be used for extended side remarks. (Why: side remarks buried in parentheses are easy to miss and hard to translate.) * When a parenthetical includes an extra idea, condition, or step, split the sentence into two sentences or move the extra idea into its own sentence or list item instead of nesting it in parentheses. (Why: one idea per sentence is easier to parse and localize.) * Where a parenthetical is necessary for precision, keep it short and avoid chaining more than one set of parentheses in the same sentence. (Why: multiple nested asides make sentences hard to read.)
## Punctuation and mechanics [#6-punctuation-and-mechanics] Objective. Remove ambiguity and increase scan speed with consistent mechanics. (Why: predictable punctuation choices make sentences easier to parse and reduce misreads.) ### 6.1 Commas, colons, semicolons [#61-commas-colons-semicolons] * The Oxford (serial) comma **MUST** be used in lists of three or more items: “nodes, wallets, and explorers.” (Why: prevents ambiguity about whether the last two items are grouped.) * Comma splices **MUST NOT** occur. If two clauses can stand alone, use a period or a coordinating conjunction. (Why: run-on sentences are hard to scan; separating clauses improves clarity.) * Bad: “The node restarts, it begins syncing.” * Good: “The node restarts. It then begins syncing.” * Colons **SHOULD** introduce lists or explanations after a complete clause. Semicolons **SHOULD** be rare. Prefer shorter sentences. (Why: correct colon use signals structure; semicolons slow scanning and can often be replaced by periods.) ### 6.2 Quotation marks and emphasis [#62-quotation-marks-and-emphasis] * Quotation marks **MUST** be used only for actual quotations or literal UI text/messages, not for emphasis. (Why: quotes indicate exact strings; using them for emphasis misleads readers and translators.) * Good: The error message “Account not found” appears. * Bad: The “validator” node… (do not quote terms) * House rule — quoting style: Use the international style with American spelling. Quotation punctuation **MUST** remain outside closing quotes unless it is part of the quoted text. This differs from American book style; keep it consistent. (Why: keeps code-adjacent strings accurate and avoids adding punctuation that isn’t part of the literal.) \[HIGH] * Use double quotation marks for log/error strings and other literal UI text when quoting it as text; place punctuation outside unless it is part of the string. (Why: quotes remain the convention for messages/text and keep literals copyable.) * This rule applies to quoted UI/log/error strings only; it does not apply to code spans or headings. (Why: code spans and headings have their own styling rules.) * Log messages and error strings **MUST** appear verbatim in quotation marks; **MUST NOT** add emphasis or change casing/punctuation. (Why: exact copying/grepping depends on matching strings.) \[HIGH] * When referencing interactive controls or keyboard keys that the reader should click or press, you **MUST** use `Label` for the control or key name. You **MUST NOT** use quotation marks, bold, or italics to style controls in instructions. (Why: `` is designed for controls/keys and keeps actions easy to scan and copy.) * Good: Click `Settings`, then select `Network`. * Bad: Click “Settings” or **Settings**. * UI or menu labels that appear in screenshots or descriptive text but are not being presented as actions **MAY** be written in quotes. Avoid mixing `` and quoted labels arbitrarily; prefer one style consistently within a page/section. For quoted UI strings, follow the house quoting style above. Punctuation follows normal sentence rules outside ``. (Why: consistent styling keeps text readable and copyable.) * Error codes/identifiers **MUST** use code formatting: `ERR_FEE_TOO_LOW`, `EADDRINUSE`, `ENOENT`. (Why: code styling distinguishes tokens from prose and aids scanning and copy/paste.) * When paraphrasing behavior, you **MUST NOT** alter message semantics; label paraphrases clearly and avoid quotation marks. (Why: altered wording leads to mismatches during troubleshooting.) #### Emphasis (bold and italics) [#emphasis-bold-and-italics] * Bold and italics **SHOULD** be used sparingly in body text. Prefer structure (headings, lists), precise wording, or an admonition over visual emphasis. (Why: heavy emphasis reduces scan speed and harms raw-Markdown readability.) ##### Bold [#bold] * Bold **SHOULD** mark scan points: a skimming reader should be able to bounce between bolded words and still understand the key actions or constraints in a section. (Why: using bold as a scan path keeps pages easy to scan.) * Use bold for a few critical words in a heading or paragraph, not whole sentences. If the paragraph still communicates the same information when bold is removed, prefer plain text and drop the bold. (Why: unnecessary bold increases noise without adding meaning.) * You **MUST NOT** bold entire sentences, paragraphs, or whole list items. If a label is needed, use a heading or an appropriate callout instead. (Why: large bold blocks create visual noise and duplicate heading semantics.) \[HIGH] * You **MUST NOT** use bold to style tokens, flags, filenames, or UI/log messages; use code font for tokens, quotation marks for log/error strings and UI text, and `` for UI/menu labels and key names. (Why: consistent, literal styling keeps examples copy-pasteable, searchable, and accessible.) \[HIGH] * Within a paragraph, you **SHOULD NOT** use more than one short bold span (≤ 3 words). Reserve it for rare emphasis that clarifies meaning, not for decoration. (Why: limiting emphasis keeps true highlights noticeable.) ##### Italics [#italics] * Italics **MAY** be used for first-mention term emphasis or titles of publications, books, papers, or standards. Avoid using italics for recurring emphasis in procedures. (Why: minimal, conventional italics aid comprehension.) * When introducing an important concept on a concept or explanation page and a glossary link is not attached, you **MAY** italicize the first meaningful mention to signal definition, then stop italicizing later mentions. (Why: one highlighted introduction is enough to draw attention without cluttering the scan path.) * Use italics for subtle emphasis that matters in sentence context but should not become a scan target. Use bold when the reader should find a word while scanning quickly. (Why: separating roles for bold and italics keeps both predictable.) * Link text **MUST NOT** be styled with bold or italics. Do not wrap links in emphasis (for example, `**[Foo](https://docs-op93jxul6-ton-core-docs.vercel.app/llms/foo/content.md)**`, `_ [Foo](https://docs-op93jxul6-ton-core-docs.vercel.app/llms/foo/content.md)_`) and do not put bold or italic markup inside the link label. When the link label is a code identifier, use inline code as the label (for example, ``[`foo_bar`](https://docs-op93jxul6-ton-core-docs.vercel.app/llms/ref/foo_bar/content.md)``). (Why: links are already visually distinct; extra emphasis adds noise and makes scanning harder.) \[HIGH] ### 6.3 Code styling [#63-code-styling] * Code, filenames, paths, API endpoints, flags, and literals **MUST** use code formatting (inline backticks or fenced blocks). **MUST NOT** add punctuation inside code that isn’t part of the code. (Why: visual separation prevents misreading and keeps examples copy-pasteable without edits.) \[HIGH] ### 6.4 Lists [#64-lists] * Use numbered lists for procedures and bulleted lists for unordered sets. If list items are full sentences, **SHOULD** end with periods; otherwise, omit terminal punctuation consistently. (Why: matching list type to purpose improves comprehension; consistent punctuation keeps visual noise low.) * Unordered list markers **MUST** be `-` (hyphen). **MUST NOT** use `*` or `+`. (Why: a single marker keeps diffs cleaner and avoids mixed styles.) * Ordered lists **MUST** use `1.` for every item; let the MDX parser auto-number in the rendered output. (Why: auto-numbering prevents renumber churn when inserting/reordering steps.) ### 6.5 Thematic breaks [#65-thematic-breaks] * Thematic breaks / horizontal rules (`---`, `***`, `___`, or HTML `
`) **MUST NOT** be used. Use headings, whitespace, or an admonition to separate sections. (Why: horizontal rules fragment structure, reduce screen-reader/navigation cues, and add noise in raw Markdown.) * You **MUST NOT** simulate separators with repeated characters or ASCII art (e.g., `=====`, `-----`). (Why: pseudo-rules create the same problems and look like code noise.) * This rule does not apply to YAML frontmatter delimiters `---` at the top of a file. Frontmatter **MAY** use `---` as required by the site generator. (Why: frontmatter is metadata, not content.) ### 6.6 Blockquotes [#66-blockquotes] * Blockquotes **MUST** be reserved for literal quotations from a source (another page in these docs or an external source). Include attribution inline or in the sentence introducing the quote; internal quotes **SHOULD** link to the exact anchor; external quotes **SHOULD** link to the canonical HTTPS source. (Why: clear attribution preserves trust and lets readers verify context.) * Blockquotes **MUST NOT** be used for callouts/admonitions, warnings, tips, examples, emphasis, or general instructions. Use the `` component for callouts (see [§11.2](#11-2-how-to-write-the-callout), [Appendix A](#a-admonition-levels-and-usage)) and headings/lists for structure. (Why: misusing blockquotes harms structure, accessibility, and localization.) * Visual callouts (Note/Tip/Caution/Warning) **MUST** use only the `` component. The only supported `type` values are `"note"`, `"tip"`, `"caution"`, and `"danger"`; do **NOT** use other components or type values. \[HIGH] (Why: a single component and fixed types keep rendering, accessibility, and localization consistent.) * Short phrases or UI/log strings **SHOULD** use inline quotation marks instead of a blockquote. Tokens and identifiers **MUST** use code font, not blockquotes. (Why: inline quotes and code font are more precise and copy-friendly.) * Keep quotations brief (prefer ≤ two sentences or one short paragraph). For longer material, summarize in your own words and link to the source. (Why: long quotes impede scanning and duplicate external content.) * Nested blockquotes **MUST NOT** be used. Quoted code or output **SHOULD** appear in fenced code blocks with attribution above the block, not inside a blockquote. (Why: fenced blocks remain copy-pasteable and render consistently.)
## Headings and titles [#7-headings-and-titles] Objective. Make navigation obvious and sections self-explanatory. (Why: clear, self-describing headings reduce misclicks, speed scanning, and make deep links understandable out of context.) ### 7.1 Case and form [#71-case-and-form] * Site-managed H1. Pages **MUST NOT** include an in-body H1. The page title is provided by the site generator/frontmatter. The first visible heading in the page content **MUST** be an H2. (Why: the template renders the title; omitting an in-body H1 avoids duplicate titles and keeps a consistent heading hierarchy.) * In MDX content, you **MUST NOT** write `# ` (H1), `

`, or use components that render an H1. Start headings at `##` (H2). (Why: syntax-level bans prevent accidental H1s in raw Markdown/MDX and keep navigation consistent.) * Imported snippets/partials **MUST NOT** emit H1 headings; they **MUST** begin at H2 or lower within the host page’s hierarchy. (Why: embedded content inherits the page’s structure and must not reset the heading level.) * All headings **MUST** use sentence case (capitalize only the first word and proper nouns). (Why: sentence case is easier to read, avoids random capitalization, and localizes more reliably.) \[HIGH] * Task (procedure) headings **MUST** start with an imperative verb; concept headings **SHOULD** be noun phrases. (Why: imperatives signal actions the reader takes; noun phrases signal explanatory content, improving navigation and search relevance.) * Task: “Deploy a validator.” * Concept: “Validator architecture.” * How-to titles. For the How-to doc type, the page title **MUST** follow “How to X”. Internal section headings (H2/H3) remain imperative. (Why: the pattern clarifies page type and improves discoverability without changing procedural heading style.) ### 7.2 Gerunds and labels [#72-gerunds-and-labels] * For task/procedure headings (H2/H3), gerunds (e.g., “Creating…”, “Configuring…”) **SHOULD NOT** be used. Prefer imperative verbs. (Why: gerunds are vague about action vs. state; imperatives are clearer and translate better.) * Concept headings **MAY** use concise noun phrases (e.g., “Naming”, “Spelling”, “Versioning”). (Why: short labels act as clear section tags and improve scan speed.) * Fixed labels like Troubleshooting, Changelog, or FAQ are acceptable. Imperatives read cleaner and translate better in procedural sections. (Why: common labels match user expectations and TOC patterns; imperatives keep steps actionable.) * House default: use “Troubleshoot” by default; “Troubleshooting” is acceptable when aligning with established ecosystem conventions. (Why: one default reduces variance; allowing the alternate keeps external consistency where needed.) ### 7.3 Uniqueness and linkability [#73-uniqueness-and-linkability] * Headings **MUST** be unique at the same nesting level within a page and **MUST** make sense out of context (as TOC/sidebar links). Avoid repeated “Introduction” sections; prefer specific names. (Why: unique, descriptive headings prevent anchor collisions and make links meaningful in search and sharing.) ### 7.4 Formatting restrictions [#74-formatting-restrictions] * Headings **MUST NOT** contain styling other than text: no bold, italics, `code`, quotes, or ALL CAPS (acronyms permitted). Keep headings clean; use formatting in body text only. (Why: extra styling harms scannability, clutters the TOC, and causes inconsistent rendering.) * Exceptions: * Reference pages only: Headings **MAY** include code font for identifiers (API names, flags, error codes), e.g., `tvm.runvm` — interface and exit codes. (Why: monospaced identifiers preserve exact casing and aid search/copy.) * When the heading contains a literal UI/log/error message, quotation marks **MAY** be included (e.g., Fix “Account not found”). (Why: quoting exact strings shows what to grep or match without altering punctuation.) ### 7.5 Practical length norms [#75-practical-length-norms] * Headings **SHOULD** be concise. As a norm, Page title (site/frontmatter) ≤ \~60 characters; H2/H3 ≤ \~70 characters. Exceed only for clarity. (Why: concise titles fit sidebars and search results without truncation; brevity improves scanning.) Examples (good): * “Run a validator on testnet” (H2, imperative) * “Account model and messages in TON” (H2, concept) Examples (bad): * “Running and configuring the validator” (gerunds) * “How the `validator` works” (code in heading)

## Readability and scannability [#8-readability-and-scannability] Objective. Keep text fast to read and effortless to scan. (Why: quick comprehension reduces rereads and mistakes during implementation.) ### 8.1 Paragraphs and sentences [#81-paragraphs-and-sentences] * One idea per paragraph. Paragraphs **SHOULD** be ≤ 5 sentences; single-sentence paragraphs are acceptable for emphasis. These are recommended norms, not hard caps—exceed only when clarity requires it. (Why: tight, focused paragraphs are easier to scan; short norms keep pages consistent without blocking necessary detail.) * Each sentence **SHOULD** convey one main idea. If a sentence starts to describe two distinct actions or conditions, split it into two sentences or convert the extra actions into a list. (Why: one-idea sentences are easier to scan and translate; lists make multi-step actions obvious.) * Sentences **SHOULD** average 15–20 words. Long, multi-clause sentences **SHOULD** be split. Front-load key points. (Why: mid-length sentences reduce cognitive load; splitting prevents misreads; leading with the main point speeds understanding.) ### 8.2 Structure for scanning [#82-structure-for-scanning] * Use subheadings, lists, and tables to break up dense text. Provide breathing room around code, tables, and images (blank lines before/after blocks). (Why: chunking and whitespace make structure visible and stop content from blending together.) * Highlight critical notes with admonitions (Note/Tip/Important/Caution/Warning) sparingly so they retain impact. (Why: overuse causes readers to ignore callouts; sparing use signals importance.) * This guidance does not limit required safety callouts in [§11](#11-safety-critical-content-blockchain-specific); when in doubt, include the safety callout. (Why: preventing harm overrides brevity and visual economy.) ### 8.3 Micro-examples [#83-micro-examples] Before (hard to scan): “After deploying, if fees are misconfigured, the transaction might fail and the node logs a warning; you can retry after adjusting the config, but it’s better to verify the fee policy first because otherwise the wallet may reject the message.” After (scannable): * Verify fees before deploying. * If the transaction fails with `FEE_TOO_LOW`: 1. Update the fee policy. 2. Retry the deployment. * The node logs a warning on failure.
## Recommended page structures (by type) [#9-recommended-page-structures-by-type] Objective. Make pages predictable without forbidding alternatives. (Why: predictable shapes reduce scanning time and help readers know what to expect.) Rule. The patterns below are **RECOMMENDED**. You **MAY** deviate when another structure improves clarity, but pages in the same section **SHOULD** be consistent. (Why: consistency within a section helps navigation and comparison; flexibility allows better fit for edge cases.) ### 9.1 Step by step (first success) [#91-step-by-step-first-success] Recommended sections: Objective → Prerequisites → Steps (3–7) → Verify (expected output or result) → Troubleshoot (common errors) → Next steps. Keep Next steps minimal (1–3 essential links) or omit when the path is linear. (Why: this flow gets newcomers to a working result, confirms success, handles common failures, and points to what to do next.) Notes: Keep a single happy path; theory **SHOULD** be limited to ≤ two bullets and linked to an Explanation page. (Why: branching and long theory cause drop-offs; brief links keep momentum while offering depth when needed.) Example outline (good): * Objective: “Deploy a counter contract on testnet.” * Prerequisites: Node.js 20+, TON SDK JS, funded testnet wallet, ``. * Steps: 1) Initialize project … 2) Compile … 3) Deploy … * Verify: “Expected output” block showing successful deployment. * Troubleshoot: `INSUFFICIENT_FUNDS`, `INVALID_WORKCHAIN` fixes. * Next steps: Link to contract upgrades guide. ### 9.2 How-to guides (goal-oriented procedures) [#92-how-to-guides-goal-oriented-procedures] Recommended sections: Goal → Prerequisites → Steps → Result → Links to Reference (anchor each flag/param). (Why: the reader sees what they’re trying to achieve, what they need, how to do it, what outcome to expect, and where to look up details.) Notes: Do not embed long background; link to concepts instead. Keep each step a single action with sub-bullets for options. (Why: separating theory prevents duplication and keeps the guide tight; one action per step reduces ambiguity and errors.) ### 9.3 Explanations (concepts/why) [#93-explanations-conceptswhy] Recommended sections: What/Why → Core concepts → Trade-offs → Related topics. (Why: this order frames purpose first, then explains mechanics, then consequences, and finally directs to adjacent ideas.) Notes: Avoid command sequences. Use diagrams and short examples to illustrate concepts. (Why: commands distract from understanding; visuals and minimal examples clarify ideas without turning the page into a procedure.) ### 9.4 Reference (complete, factual) [#94-reference-complete-factual] Recommended sections: Summary → Parameters/Fields (tables) → Returns/Responses → Errors (codes, meanings) → Examples (minimal usage) → Optional See also (1–3 essential anchors). (Why: a uniform, tabular layout makes lookups fast and supports deep linking and automation.) Notes: Be exhaustive and anchor-linkable; minimize narrative. Keep formats consistent across entries. (Why: completeness and anchors enable precise links from guides; minimal prose speeds lookup; consistency lets readers scan different entries the same way.)
## Code and command examples [#10-code-and-command-examples] Objective. Ensure examples are precise, copy-pasteable, and unambiguous. (Why: readers should be able to run examples without editing or guessing.) ### 10.1 General rules [#101-general-rules] * Examples **MUST** be copy-pasteable. **MUST NOT** include shell prompts (`$`, `>`) in command blocks. (Why: prompts get copied accidentally and break commands.) \[HIGH] * Command and expected output **MUST** be presented as separate fenced blocks. (Why: mixing them causes copy errors and makes results hard to recognize.) \[HIGH] * Placeholders **MUST** use `` (e.g., ``, ``), and each placeholder **MUST** be defined on first use. (Why: a consistent, visible pattern prevents pasting unsafe hard-coded values.) \[HIGH] * Fenced code blocks **MUST** specify a language (` ```bash `, ` ```rust `, ` ```json `, …). (Why: language tags enable correct highlighting and tooling.) * Filenames shown in examples **MUST** be realistic and kebab-case (e.g., `wallet-config.json`, not `MyConfig.json`). (Why: examples should model the conventions we require elsewhere.) * Long commands **MUST NOT** be hard-wrapped. Prefer UI soft wrap. If a tool supports safe line continuation (e.g., `\` in POSIX shells), continuation **MAY** be used and must be copy-pasteable as shown. (Why: hard wraps break execution; soft wrap or continuations keep commands runnable.) * You **SHOULD** favor examples that run end-to-end on testnet by default. (Why: safer defaults reduce risk and support quick validation.) * Inside language code, placeholders **SHOULD** be neutral (e.g., `UPPER_SNAKE` inside strings or comments) when angle brackets would clash with language syntax; in commands and prose, placeholders **MUST** use ``. (Why: avoids syntax errors in code while keeping a single placeholder style in prose/CLI.) * In runnable examples, configuration values and other parameters that the reader is expected to change **MUST** be collected in one clearly visible block near the top of the snippet. When the language allows top-level declarations, this block **MUST** use top-level constants instead of redefining values inside the entry function or helpers; when the language forbids top-level declarations, group these parameters at the start of the entry function. (Why: collecting adjustable values in one visible place makes examples easier to understand and update.) \[HIGH] ### Error and log style [#error-and-log-style] * Quoted UI/log messages **MUST** appear verbatim in quotation marks. (Why: exact strings are searchable and prevent confusion.) * Error codes and identifiers **MUST** be rendered in code font (e.g., `ERR_FEE_TOO_LOW`). (Why: monospace distinguishes tokens and aids copy/paste.) * When summarizing behavior instead of quoting, **MUST NOT** change semantics and avoid using quotes; indicate that it is a summary. (Why: paraphrases should not be mistaken for literal messages and must stay accurate.) Good: ````text ```bash ton-node start --ledger --network testnet ``` There, `` — path to the local ledger directory. `` — HTTPS endpoint of the TON RPC provider. Expected output: ```text Node started. Workchain: 0 Shard: -1 Status: running ``` ```` Bad: ````text ```bash $ ton-node start --ledger /home/bob/ledger --network mainnet # includes prompt, hard-coded values ``` ```` ### 10.2 Partial snippets [#102-partial-snippets] * Partial snippets (focused excerpts) **MAY** be used when teaching a narrow concept, even if not runnable alone. (Why: small, targeted examples clarify one idea without setup noise.) * Partial snippets **MUST** be labeled clearly above the block: “Not runnable”. (Why: prevents readers from attempting to execute incomplete code.) * Partial snippets **SHOULD** link to a full runnable example or reference entry showing complete context. (Why: gives readers a path to working code.) Not runnable ```rust let to = Address::from_str("EQC_REPLACE_WITH_ADDRESS").unwrap(); let amount = Coins::from_nano(1_000_000_000); let body = build_transfer_body(to, amount); ``` ### 10.3 Safety and secrets in code [#103-safety-and-secrets-in-code] * Secrets (keys, mnemonics, API tokens) **MUST NOT** appear in examples. Use placeholders or test keys that are clearly invalid. (Why: prevents accidental leaks and unsafe copying.) \[HIGH] * Commands that could cause loss of funds or data **MUST** be guarded by a Warning/Caution per [§11](#11-safety-critical-content-blockchain-specific) and **SHOULD** default to testnet. (Why: explicit risk labeling and safe defaults protect readers.) \[HIGH] ### 10.4 OS and language variants [#104-os-and-language-variants] * When steps differ by OS or language, you **SHOULD** provide tabs or distinct subsections (e.g., Linux / macOS / Windows; JS / Python / Rust). (Why: separates platform differences so readers don’t mix instructions.) * If only one variant is provided, the page **MUST** state that limitation. (Why: sets expectations and avoids readers searching for missing variants.) ### 10.5 Comments and omissions [#105-comments-and-omissions] * Use language-appropriate comments to mark omissions (`// …`); **MUST NOT** use literal ellipses that change syntax. (Why: literal ellipses can create invalid code.) \[HIGH] * Explanatory comments in examples **MUST** appear on their own line immediately above the code they describe; **MUST NOT** use trailing end-of-line comments such as `foo(42); // sends a test message` in documentation snippets. (Why: stacked comment-then-code is easier to scan and keeps copy-pasted lines clean.) \[HIGH] * Exception: Fift and TVM assembly stack comments **MAY** appear as trailing end-of-line comments to show the stack state at that point (e.g., `1 2 + // 3`). This is idiomatic in stack-based languages and aids comprehension. (Why: stack comments are a well-established convention in Fift and TVM assembly; forcing them to a separate line would harm readability.) * Keep comments minimal and instructional; avoid commentary or humor. (Why: extraneous remarks distract from the task and age poorly.)
## Safety-critical content (blockchain-specific) [#11-safety-critical-content-blockchain-specific] Objective. Prevent reader harm when funds, keys, or validator/network state are involved. (Why: mistakes here can cause irreversible loss or outages.) ### 11.1 When a safety callout is required [#111-when-a-safety-callout-is-required] A Caution or Warning **MUST** appear when a page or step: (Why: visible callouts make risk obvious before a reader runs a command.) \[HIGH] * moves funds or changes fee/withdrawal behavior; (Why: users can lose money or block withdrawals.) \[HIGH] * exposes, stores, or transmits private keys/mnemonics; (Why: leaked secrets allow account takeover and theft.) \[HIGH] * modifies validator configuration, networking, or consensus-affecting parameters; (Why: misconfiguration can halt or fork nodes and degrade the network.) \[HIGH] * performs chain-affecting operations (e.g., resharding, pruning, halting, replay). (Why: these actions can corrupt the state, reduce availability, or cause data loss.) \[HIGH] If page has many actions potentially requiring a safety callout, you **MAY** combine these into a page-level safety summary plus short local callouts instead of repeating full details every time. (Why: a shared summary avoids repetition while still making risks visible.) ### 11.2 How to write the callout [#112-how-to-write-the-callout] A page that contains safety-critical actions **MUST** clearly communicate all of the following, either in a page-level safety summary, in local callouts near each step, or in combination: (Why: readers need to know the risk, scope, recovery, and safe environment before proceeding.) \[HIGH] 1. Risk (what can go wrong), (Why: sets severity and helps decide whether to proceed.) 2. Scope (what the command affects), (Why: clarifies blast radius—single node, wallet, or network.) 3. Rollback/mitigation steps where feasible, and (Why: gives a path to recovery or damage control.) 4. Environment label (testnet vs mainnet) with safer default instructions first. (Why: testnet reduces harm; explicit labels prevent accidental mainnet use.) * These elements describe the information the reader needs; they are **NOT** required as literal labels such as “Risk:” or “Scope:”. Safety callouts **SHOULD** read as concise, natural prose rather than templated checklists. (Why: natural language is easier to read and avoids robotic, placeholder-style warnings.) Common patterns: * Page-level safety summary. Place a single `` near the top of the guide that describes overall risk, scope, rollback/mitigation strategy, and testnet/mainnet expectations for the full set of commands. (Why: one visible summary prevents readers from missing critical context.) * Local step-level warnings. Add short `` elements next to each hazardous step that call out the specific risk or environment for that step and, when needed, refer back to the page-level summary instead of repeating full details (for example, “See the safety note at the top of this page before running this on mainnet.”). (Why: local notes tie the warning to the exact action without duplicating the whole summary.) Rendering (component) \[HIGH] * Safety callouts **MUST** use the `` component; **MUST NOT** use Markdown blockquotes (`>`) or headings to simulate warnings. (Why: a single component keeps appearance, accessibility, and behavior consistent.) * Mapping: use `type="caution"` for Caution; use `type="danger"` for Warning. Set an explicit `title` when needed (e.g., `title="Funds at risk"`). (Why: consistent severity mapping aligns wording with visual severity.) * Allowed types: The only supported `` `type` values are `"note"`, `"tip"`, `"caution"`, and `"danger"`. Do not use other values (e.g., `"important"`, `"warning"`). To display those labels, set `title` (e.g., `title="Important"`) while keeping a supported `type`. (Why: keeping to the supported set ensures consistent rendering and avoids runtime fallbacks.) Example (MDX) ````mdx Sending TON on mainnet is irreversible. Start with a small transfer on TON Testnet, then repeat on TON Mainnet only after checking the address and network carefully; there is no rollback on mainnet. ```bash jetton transfer --to --amount --network testnet ``` ```` ### 11.3 Safer defaults [#113-safer-defaults] * Task pages **SHOULD** use testnet endpoints by default and mention the switch to mainnet explicitly. (Why: safe defaults prevent costly mistakes.) * Destructive flags (e.g., `--purge`, `--force`) **MUST** be opt-in and accompanied by a callout. (Why: explicit opt-in and warnings reduce accidental data loss.) \[HIGH] ### 11.4 Key handling and storage [#114-key-handling-and-storage] * Keys **MUST** be represented as placeholders or generated ephemeral testing artifacts. (Why: prevents real secrets from being copied into scripts or screenshots.) \[HIGH] * In guides, prefer environment variables or keystores; never inline secrets. (Why: avoids persisting secrets in history, logs, or source control.) \[HIGH] * Reference pages **MAY** document secure storage options but **MUST NOT** encourage unsafe patterns. (Why: guidance is helpful, but normalizing bad practices leads to leaks.) \[HIGH]
## Links and cross-references [#12-links-and-cross-references] Objective. Reduce duplication and let readers jump straight to detail. (Why: direct links cut search time and prevent restating facts in multiple places.) ### 12.1 Link text [#121-link-text] * Link text **MUST** be descriptive and indicate the destination. You **MUST NOT** use generic labels like "click here", "here", "this", "this link", "this page", or bare URLs as link text. \[HIGH] (Why: meaningful text lets readers scan quickly to determine where a link leads; generic labels force readers to examine surrounding context.) * You **MUST NOT** use mechanics-focused verbs like "click", "tap", "follow", or "go to" as part of link text. Focus on content, not interaction mechanics. \[HIGH] (Why: drawing attention to the clicking action distracts from the content; not all users click — some tap, use keyboards, or use assistive technology.) * Link text **SHOULD** describe the destination, not the action of navigating. One effective technique: use the title or topic of the target page as the link text and integrate it into the sentence. * Bad: `"To learn about fees, click [here](https://docs-op93jxul6-ton-core-docs.vercel.app/llms/fees/content.md)."` * Bad: `"Click [here](https://docs-op93jxul6-ton-core-docs.vercel.app/llms/fees/content.md) for fee information."` * Bad: `"[This page](https://docs-op93jxul6-ton-core-docs.vercel.app/llms/fees/content.md) explains fees."` * Good: `"The [fee structure](https://docs-op93jxul6-ton-core-docs.vercel.app/llms/fees/content.md) determines transaction costs."` * Good: `"Transaction costs depend on the [fee structure](https://docs-op93jxul6-ton-core-docs.vercel.app/llms/fees/content.md)."` * When a link must stand alone (e.g., at the end of a sentence or after a colon), make the link text self-explanatory: * Bad: `"For more details, see [here](https://docs-op93jxul6-ton-core-docs.vercel.app/llms/validator-setup/content.md)."` * Good: `"For more details, see [Validator setup](https://docs-op93jxul6-ton-core-docs.vercel.app/llms/validator-setup/content.md)."` * Good: `"Related guide: [Set up a validator](https://docs-op93jxul6-ton-core-docs.vercel.app/llms/validator-setup/content.md)."` * Link labels **SHOULD** be plain text or inline code for identifiers (see [§6.2](#6-2-quotation-marks-and-emphasis) for emphasis restrictions on link text). (Why: unstyled labels keep links readable and avoid redundant visual emphasis.) * Standalone "stub" sentences whose only job is to say "See …" or "Read here …" followed by a link (for example, `[Read here](https://docs-op93jxul6-ton-core-docs.vercel.app/llms/standard/wallets/mnemonics/content.md) to learn more.` or `See [mnemonics](https://docs-op93jxul6-ton-core-docs.vercel.app/llms/standard/wallets/mnemonics/content.md) for more details.`) **MUST NOT** appear in running prose. Instead, attach the link to the relevant term or phrase in a normal sentence (for example, `The [mnemonics guide](https://docs-op93jxul6-ton-core-docs.vercel.app/llms/standard/wallets/mnemonics/content.md) explains why.`). (Why: inline links keep the text flowing and avoid postponing useful links to trailing meta-sentences.) \[HIGH] * Accessibility and SEO note: Screen readers often present links out of context (e.g., a list of all links on a page). Generic link text like "here" or "click here" becomes meaningless when read in isolation. Search engines also use link text to understand page relationships. Descriptive link text improves both accessibility and discoverability. (Why: links must make sense without surrounding prose.) ### 12.2 What to link (and what not) [#122-what-to-link-and-what-not] * In a guide, the first useful mention of a flag, parameter, error code, or data type on the page **MUST** link to the canonical reference anchor. You **MAY** also link its first mention in other H2/H3 sections on long pages that are frequently deep-linked or read out of order. (Why: readers see the spec at the moment they need it, even when entering mid-page.) \[HIGH] * This rule explicitly includes TVM exit codes (e.g., `-13`, `37`), send modes (e.g., `mode 64`, `mode 128`), reserve modes, and similar numeric constants that have documented meanings. These **MUST** be linked to their corresponding reference anchors on first mention, not left as bare code spans. (Why: numeric constants are opaque without context; links let readers understand them instantly.) \[HIGH] * Within a single H2/H3 section, link only the first meaningful mention of an important term or reference target. When the same term appears in a different H2/H3 section, you **MAY** link its first mention again there. Avoid linking every occurrence inside one section; add a repeated link only when separated by many screens and it clearly helps the reader. (Why: per-section first links help when deep-linking to a subsection without turning the page into a link farm.) * Link concepts judiciously: if the reader is likely to wonder “what does that mean?”, link the term on its first useful mention in that H2/H3 section. Subsequent mentions in the same section **SHOULD** be plain text unless the gap is large and a repeated link clearly helps. (Why: section-local first links help readers who land on a deep link without over-linking common words.) * On the first useful mention of a core TON term on a page, you **SHOULD** link to the Glossary (Foundations → Glossary), unless the page itself defines it. On long pages, you **MAY** also link the first mention of that term in other H2/H3 sections, following the per-section rules above. (Why: keeps definitions consistent and easy to find while still helping readers who enter mid-page.) * Over-linking common words is discouraged; link what is plausibly useful. (Why: excessive links slow reading and distract from the task.) * Guides **MUST NOT** duplicate reference tables; summarize and link instead. (Why: duplication drifts and creates conflicting sources of truth.) * Internal first. When both an internal TON Docs page and an external source exist, you **MUST** link the internal page by default (including instead of the TEPs repository). Exception: pages whose purpose is to document a standard contract/TEP **MAY** also link the corresponding TEP as the canonical spec. If no relevant internal page exists, linking to the external source is acceptable. (Why: internal pages are newcomer-friendly; TEPs are normative but hard to parse for new readers.) Example (good) Start the node with `--threads` (see [validator flags → `--threads`](https://docs-op93jxul6-ton-core-docs.vercel.app/llms/ecosystem/nodes/overview/content.md)) to increase parallelism. ### 12.3 Link targets and format [#123-link-targets-and-format] * Internal links **MUST** be root-absolute and stable (start with `/`), yet relative to the `content/` directory; anchors **MUST** resolve correctly. **MUST NOT** use relative segments like `./` or `../` in Markdown/MDX link URLs or HTML/JSX. (Why: files and folders move frequently; root-absolute links remain correct across moves; relative segments are brittle and costly to maintain.) \[HIGH] * Cross-section links **SHOULD** deep-link to the exact section or anchor instead of the page top. (Why: deep links land readers on the exact answer.) * A See also section **MAY** close a page with 1–3 essential links; prefer a linear path that needs none. (Why: minimal exits keep readers on task while still offering critical follow-ups.) * When linking to the same internal target multiple times on a page, you **SHOULD** prefer reference-style Markdown links so the URL appears once in a shared definition block. For example: ```md Use the [jetton wallet][jetton-wallet] contract where applicable; the [jetton wallet reference][jetton-wallet] describes all fields. [jetton-wallet]: https://docs-op93jxul6-ton-core-docs.vercel.app/llms/content/standard/jettons/wallet/content.md ``` This keeps body text readable and makes URL updates cheaper, while still requiring root-absolute URLs in the reference definition. (Why: shared link definitions reduce visual noise and simplify maintenance.) ### 12.4 Avoid circularity and drift [#124-avoid-circularity-and-drift] * Each fact **MUST** have a single canonical home. If you need the same fact elsewhere, link to it. (Why: one source avoids conflicting copies and simplifies updates.) * **MUST NOT** link to outdated or superseded pages except when documenting historical behavior. (Why: stale links propagate errors and erode trust.) \[HIGH] ### 12.5 Images and media [#125-images-and-media] * Images **MUST** be embedded using the `` MDX component. Markdown image syntax `![...](...)` and raw `` are **PROHIBITED**. (Why: the component provides dark-theme control, consistent sizing/zoom, and stable rendering.) \[HIGH] * Image sources **MUST** be root-absolute and live under `/public/images/`, yet be given without `/public` in the URL (for example, ``, where `` is the logical image category and `` is the filename). **MUST NOT** use relative `src` such as `./` or `../`. (Why: content moves often; root-absolute paths remain valid.) \[HIGH] * Provide a `darkSrc` when contrast or readability differs in dark mode. Keep aspect ratios consistent across a page to avoid layout shift. (Why: visual stability improves reading flow.) * SVG note: if `src` points to an SVG and `darkSrc` is omitted, the dark-theme image is auto-inverted. Supply an explicit `darkSrc` when inversion is not desired. (Why: ensures accurate colors and legibility.) * Provide meaningful, non-empty `alt` text for every image; `alt` **MUST NOT** be empty. (Why: screen readers rely on `alt` to convey image meaning; empty `alt` hides content from assistive tech.) \[HIGH] * When using ``, prefer the `width`/`height` props for predictable layout; avoid arbitrary inline styling. (Why: predictable dimensions prevent layout shift and maintain consistency.) ### 12.6 External references [#126-external-references] Objective. Use authoritative, stable sources and deep links; avoid volatile or non-authoritative pages. (Why: reliable links reduce drift, link rot, and conflicting guidance.) * Authority order. You **MUST** prefer: (1) official project documentation/specs/standards (link internal TON Docs when available before external repos); (2) vendor documentation for tools used; (3) primary sources (RFCs, papers). Community wikis/blogs **MAY** be linked only when no official source exists and **MUST** be labeled as background. (Why: authoritative sources change less and carry clearer guarantees; internal docs are optimized for comprehension.) * Wikipedia and crowd-edited sources. Wikipedia **MAY** be linked for general, well-known non-TON concepts when the link is informational and not supporting a requirement or API/behavior semantics. For normative claims or when precision matters, **MUST** link a spec or official docs (e.g., RFC 8032 for Ed25519). (Why: Wikipedia is useful for broad context; specs are stable for requirements.) * Q/A forums and social posts. Stack Overflow, Reddit, and personal blogs **MUST NOT** be used as normative references. They **MAY** appear as background in the Explanation pages when no official source exists. (Why: anecdotal content is volatile and easily outdated.) * TEPs specifics. Prefer the internal TON Docs page that explains a standard over linking directly to the TEPs repository. On pages that are themselves standards or reference docs (e.g., standard contracts), you **MAY** include a precise deep link to the corresponding TEP as the canonical spec. Avoid linking the repository root; link the exact TEP and section. (Why: TEPs are normative but difficult for newcomers; internal docs provide context while still letting experts reach the spec.) * Stable permalinks (situation-aware). When linking to specific code/files/lines or exact doc sections where content must remain reproducible, you **SHOULD** use a versioned or permanent URL (e.g., GitHub tag/commit permalink; versioned docs; DOI). If a versioned URL exists and the reference is normative or precision-critical, you **MUST NOT** link to moving targets like “main”, “HEAD”, or “latest”. For general project references (homepage or repo root), you **MAY** use the canonical current URL. (Why: permalinks keep exact references stable; simple links are fine when versioning adds no value.) \[HIGH] * Deep links. You **SHOULD** link to the exact section/anchor that holds the needed fact, not the page top. (Why: deep links land readers on the answer and reduce scanning.) * Clean URLs. Links **MUST** use HTTPS, **MUST NOT** include shorteners or tracking parameters (e.g., `utm_*`), and **MUST NOT** point to unofficial mirrors/gists when an official location exists. (Why: clean, canonical URLs are trustworthy and durable.) \[HIGH] * Language and availability. Link to the English source by default. If the authoritative page is non-English, **MUST** label the link with the language (e.g., “(in Russian)”). Avoid paywalled sources as primary; if unavoidable, **SHOULD** provide an open alternative or summarize key facts locally. (Why: sets expectations and preserves access.)
## Terminology and naming [#13-terminology-and-naming] Objective. Enforce a single source of truth for terms and casing. (Why: one authoritative lexicon prevents confusion, reduces review churn, and keeps search/indexing consistent.) ### 13.1 Term bank (canonical source) [#131-term-bank-canonical-source] * A project term bank **MUST** define canonical terms, spellings, hyphenation, casing, and banned variants with replacements (e.g., allowlist/denylist for whitelist/blacklist). (Why: clear entries stop ad-hoc wording and mixed casing from spreading.) * You **MUST** consult the term bank before introducing new names; additions **SHOULD** be reviewed by editors. (Why: gatekeeping new terms prevents drift and conflicting synonyms.) * The term bank **SHOULD** mark which terms are link-worthy for first-use cross-links and record their canonical doc URLs. First-use linking rules in [§12.2](#12-2-what-to-link-and-what-not) **SHOULD** apply only to terms above this importance threshold to avoid over-linking minor notions. (Why: a curated set of link-worthy terms keeps pages readable while still making key concepts discoverable.) * Flags, parameters, error codes, and data types documented in guides **MUST** be included in this link-worthy set so first-use links in [§12.2](#12-2-what-to-link-and-what-not) always have a canonical target. This includes TVM exit codes, send modes, reserve modes, and other numeric constants with documented semantics. (Why: treating these technical items as link-worthy ensures readers can jump straight to their reference definitions.) \[HIGH] ### 13.2 General casing rules [#132-general-casing-rules] * Generic concepts **MUST NOT** be capitalized mid-sentence (use "smart contract," not "Smart Contract"). (Why: random caps imply proper nouns and slow reading.) \[HIGH] * Proper nouns and official product/feature names **MUST** follow the term bank (e.g., TON, TON Connect). (Why: consistent branding and accurate references.) * Code identifiers (types, fields, flags) **MUST** appear in code font with exact case. (Why: preserves copy/paste fidelity and distinguishes code from prose.) \[HIGH] ### 13.3 Hyphenation and abbreviations [#133-hyphenation-and-abbreviations] * Multi-word mechanism names are common nouns and **SHOULD** be hyphenated: proof-of-stake, zero-knowledge. (Why: hyphenation clarifies compounds and matches industry norms.) * Abbreviated forms **MUST** follow the project style: ZK-proof, ZK-rollup (uppercase ZK, hyphenated compound). (Why: consistent abbreviation improves recognition and search.) * Use mainnet as a common noun; use TON Mainnet when referring to the proper name of the network. (Declare this explicitly in the term bank.) (Why: distinguishes generic network type from the named network.) * Use testnet as a common noun; use TON Testnet when referring to the proper name of the network. (Why: same distinction as mainnet; avoids mixed casing.) ### 13.4 TON-specific examples [#134-ton-specific-examples] Non-exhaustive; finalize in the term bank. (Why: examples guide writers now, while the term bank remains the single source of truth.) * TON, TON Blockchain, TON Ecosystem (proper nouns). * smart contract, wallet, account, message, jetton, nominator, validator, collator, node, liteserver (common nouns, lowercase mid-sentence). * accountchain, shardchain, workchain, masterchain, basechain — common nouns; use lowercase mid-sentence. **MUST NOT** use CamelCase forms (`ShardChain`, `WorkChain`, `MasterChain`, `BaseChain`, `AccountChain`) or spaced variants (e.g., “Shard Chain”). * BoC (abbrev.) / bag of cells (common noun). Abbreviation **MUST** be “BoC” (not “BOC”). Note: Do **NOT** introduce “master/slave” metaphors in new text; use primary/replica or similar. (Why: maintains inclusive language.) ### 13.5 Placeholder names [#135-placeholder-names] * In commands and prose, placeholders **MUST** be `` with descriptive names: ``, ``, ``. (Why: a single, visible pattern reduces copy/paste mistakes.) * In programming-language code, placeholders **MAY** use `UPPER_SNAKE` without angle brackets when `< >` would clash with syntax (see [§10.1](#10-1-general-rules)). (Why: avoids syntax errors while keeping placeholders obvious.) * **MUST NOT** use `{curly}` or `[square]` placeholder syntax in copy-pasteable commands, as they are easy to misread as literal characters. (Why: braces/brackets are often treated as literals by shells and new users.) \[HIGH] ### 13.6 Banned and preferred terms [#136-banned-and-preferred-terms] * Banned (inclusive/biased): whitelist/blacklist; master/slave; sanity check. \[HIGH] * Banned (filler/tone): simply, just, obviously, clearly, please note. * Preferred: (omit filler); allowlist/denylist; primary/replica; smoke check or basic check. Rationale: clarity, inclusivity, and reduced ambiguity.
## Numbers, units, date, and time [#14-numbers-units-date-and-time] Objective. Present quantitative information unambiguously for a global developer audience. (Why: consistent formats prevent locale-based misreads and implementation errors.) ### 14.1 Numerals and separators [#141-numerals-and-separators] * You **MUST** use numerals for all technical quantities (latency, memory, fees, block heights, versions, ports), regardless of size. (Why: digits are faster to scan and less ambiguous than words in technical contexts.) * Good: “Set the fee to 0.2 TON.” * For general prose without units, you **MAY** spell out zero–nine and use numerals for 10+, but prefer numerals whenever a value matters to a task. (Why: numbers highlight actionable values and make comparisons obvious.) * You **SHOULD** use thousands separators for numbers ≥ 10,000: 10,000, 1,234,567. (Why: separators improve readability and reduce digit-counting mistakes.) * **MUST NOT** add separators to codes/IDs (e.g., block hashes, transaction IDs, addresses), even if they contain digits; keep copyable values intact. (Why: added punctuation breaks copy/paste and changes identifiers.) \[HIGH] * Decimal separator **MUST** be a dot: 3.1415. (Why: a single convention avoids comma/dot confusion across locales and matches most APIs.) ### 14.2 Units and conventions [#142-units-and-conventions] * Use binary units (KiB, MiB, GiB) for memory/storage sizes and SI units (kB, MB, Gbps, ms) for network throughput, latency, and timing. Be consistent within each category. (Why: binary vs SI units have different meanings; consistency prevents 2× errors.) * Currency amounts **MUST** specify the unit (e.g., TON, USDT). When precision matters, show decimals explicitly (e.g., 0.000001 TON). (Why: omitting units or precision leads to costly misinterpretation.) \[HIGH] * Address/hash values **MUST NOT** be silently truncated. If truncation aids readability, use a consistent truncation pattern (e.g., first 4 / last 4 with an ellipsis: `EQC…9gA`) and state clearly that the value is truncated. (Why: silent truncation causes copy/paste failures and verification mistakes.) \[HIGH] ### 14.3 Dates and times [#143-dates-and-times] * Dates **MUST** use ISO-8601 format YYYY-MM-DD (e.g., 2025-02-11). (Why: ISO is unambiguous and sorts correctly.) * Times **SHOULD** be 24-hour and, where relevant, UTC (e.g., 14:30 UTC). (Why: avoids AM/PM ambiguity and timezone drift.) * Use UTC for timestamps that might be compared across regions (e.g., transactions, block times, cron examples). (Why: a single timezone ensures consistent ordering and comparison.) * Ranges **MUST** be explicit: 2025-02-11 14:30–15:00 UTC. (Why: clear start/end with timezone prevents misaligned windows.) * **MUST NOT** use ambiguous forms like `11/2/2025`. (Why: day/month order varies by locale and leads to errors.) * Changelogs **SHOULD** include a date stamp in ISO format. (Why: stable, sortable dates aid release tracking.) ### 14.4 Magnitudes and math [#144-magnitudes-and-math] * Prefer engineering prefixes for readability: 1.2 GiB, 250 ms, 500 kB/s. (Why: normalized units make scale comparisons quick and reduce cognitive load.) * Inline math **SHOULD** use KaTeX/LaTeX components when formulas help clarity. (Why: consistent rendering and accessibility across themes and locales.) Rationale: Consistent numeric style reduces misreads and eases localization.
## Accessibility and internationalization [#15-accessibility-and-internationalization] Objective. Ensure content is usable by all readers and easy to localize. (Why: accessible, localization-ready text works for non-native readers, assistive technologies, and translations without rewrites.) ### 15.1 Language and reading [#151-language-and-reading] * Content **MUST** use plain, international English; avoid idioms, slang, and culture-specific metaphors. (Why: idioms and slang do not translate well and confuse global readers.) * Link text and headings **MUST** be descriptive (screen-reader friendly). Avoid “click here” (see [§12](#12-links-and-cross-references)). (Why: descriptive text improves scanning and is meaningful when read aloud by assistive tech.) * Avoid gendered or ableist terms; use inclusive alternatives (see [Appendix B](#b-banned-and-preferred-terms)). (Why: inclusive language prevents exclusion and avoids unnecessary friction.) ### 15.2 Structure and tables [#152-structure-and-tables] * Tables **SHOULD** include header rows; keep cell content short and scannable. (Why: headers provide context for readers and screen readers; brief cells are easier to parse.) * Units **MUST** be shown in headers or cells (e.g., “Latency (ms)”, “Size — MiB”). (Why: explicit units prevent misinterpretation of values.) * Columns whose cells are primarily numeric values (for example, counts, sizes, fees, percentages, timings) **MUST** be right-aligned so digits line up vertically. (Why: aligned digits make numeric comparisons easier and reduce misreads.) \[HIGH] * Columns whose cells contain identifiers such as addresses, hashes, transaction IDs, or error codes are not numeric columns and **MAY** remain left-aligned. (Why: identifier strings are scanned, copied, and compared differently than numeric quantities.) * Cells **SHOULD NOT** contain multi-paragraph text; move extended explanations below the table. (Why: long prose in tables is hard to read and harms accessibility/layout.) * Long lists inside cells **SHOULD** be converted to bullet lists placed below the table. (Why: lists outside tables are easier to scan and navigate.) * Provide text alternatives for complex figures when feasible. (Why: alt or adjacent text lets screen-reader users and translators access the content.) * Keyboard-only navigation **SHOULD** be considered when adding interactive elements. (Why: some users cannot use a mouse; keyboard support is a basic accessibility need.) * Emojis **MAY** appear in compact tables as secondary indicators only when they follow a widely understood convention (e.g., `✅ Supported`, `❌ Not supported`) and are paired with clear text in the same cell. **MUST NOT** rely on emojis alone to encode meaning or status, and **MUST NOT** use decorative pictograms or one-off icons that do not have a clear, conventional meaning. (Why: paired, conventional indicators remain accessible and understandable when emojis do not render or in translation.) ### 15.3 Localization readiness [#153-localization-readiness] * Prefer stable terminology from the term bank ([Appendix B](#b-banned-and-preferred-terms) references) to minimize translation drift. (Why: consistent terms reduce rework and inconsistent translations.) * Dates/times already follow ISO conventions (see [§14.3](#14-3-dates-and-times)), which **SHOULD** simplify localization. (Why: ISO formats are unambiguous across locales and require minimal adaptation.) Rationale: Clear, inclusive writing and accessible assets improve comprehension for global audiences and translation tools.
## File, navigation, and frontmatter conventions [#16-file-navigation-and-frontmatter-conventions] Content of this section mostly describes contents of `docs.json` and `[...](...)` markdown links in `.mdx` files. ### 16.1 Sidebar groups and ordering [#161-sidebar-groups-and-ordering] Objective. Keep navigation predictable and reduce decision points. (Why: consistent ordering helps readers find the right kind of page without scanning the whole section.) Rules (binding). * The onboarding path **SHOULD** be a dedicated “Step by step” group near the top of the sidebar. Keep it linear and link out for depth. (Why: newcomers progress faster with one clear path.) * Within every topical group (e.g., Ecosystem, Language reference, Standard contracts, TVM, Foundations, Smart-contract patterns, Contribute; Integrate when present), pages **MUST** be ordered: Explanation → How-to → Reference. (Why: readers scan “why” first, then “how”, then exact details.) * The Explanation page **SHOULD** be the group’s overview (often `overview.mdx`). Keep it conceptual and brief, and link to How-to/Reference as needed. (Why: one conceptual entry frames the section and reduces duplication.) * Reference pages **MUST** be the canonical source for flags/fields/errors/types. Guides **MUST NOT** duplicate tables; they **SHOULD** deep-link to anchors. (Why: single source of truth stays accurate and reduces maintenance.) Objective. Keep repository structure and UI labels consistent. (Why: predictable structure speeds editing, improves search/TOC behavior, and reduces merge and build issues.) ### 16.2 Files and titles [#162-files-and-titles] * Filenames **MUST** use kebab-case.md or kebab-case.mdx (e.g., `validator-setup.mdx`). (Why: kebab-case avoids case-sensitivity bugs, reads well in URLs, and is easy to grep.) \[HIGH] * Filenames **MUST NOT** have uppercase characters, i.e. `foo-bAR.mdx`. \[HIGH] * Filenames **MUST NOT** have cyrillic characters, i.e. `сhoice.mdx`. \[HIGH] ### 16.3 Navigation labels [#163-navigation-labels] * Sidebar and nav labels **SHOULD** be short (2–4 words), unique, and mirror in-page headings. (Why: short, unique labels prevent truncation and speed scanning.) * Sidebar labels **MAY** be concise aliases of the page title; they **SHOULD** preserve the title’s meaning even if wording is shortened. (Why: sidebars have less space; preserving meaning avoids confusion.) * Child pages inside a sidebar group **MUST NOT** repeat the group name in `sidebarTitle` when that word adds no new meaning. Rely on the group label as context and choose a short, distinct label instead. (Why: avoiding redundant group nouns keeps nested labels concise and scannable.) \[HIGH] * Example: in a group `Addresses`, prefer `sidebarTitle: "Overview"` or `sidebarTitle: "Deriving"` over `sidebarTitle: "Addresses overview"` or `sidebarTitle: "Deriving addresses"`. * Avoid duplicate “Introduction” labels—make them specific (e.g., “Intro to sharding”). (Why: generic labels create indistinguishable TOC items and weak deep links.) * Frontmatter keys. Use only page metadata supported by Mintlify (see project docs) and `noindex: true` when a page must be excluded from search indexing. **MUST NOT** introduce custom frontmatter keys for internal taxonomy (e.g., `doc_type`, `audience`, custom `status`). Represent such information in the page content or navigation instead. (Why: unsupported keys add maintenance burden, break tooling, and confuse contributors.) * Length cap. If the frontmatter `title` exceeds 30 characters, the page **MUST** set `sidebarTitle`, and the `sidebarTitle` **MUST** be ≤ 30 characters. If the `title` is ≤ 30 characters, `sidebarTitle` is OPTIONAL; when provided, it **SHOULD** be ≤ 30 characters. Prefer removing non-essential words over truncation; labels **MUST NOT** end with ellipses; preserve meaning and proper-noun/case accuracy. (Why: short, clear labels fit sidebars and remain scannable.) Example ```mdx --- title: "How to troubleshoot validator connectivity issues on restrictive firewalls" sidebarTitle: "Validator connectivity" --- ``` * How-to frontmatter pattern. How-to pages **MUST** set `title: "How to X"` and **MUST** set `sidebarTitle` to either `X` or a shorter alias of X that relies on the sidebar group for context and does not repeat the group name needlessly, where X is the task phrased in sentence case. If X begins with a letter, capitalize its first character; preserve exact casing for proper nouns and code tokens inside X. (Why: consistent titles match “how to …” searches; concise sidebar labels aid scanning while avoiding redundant group nouns and keeping identifiers accurate.) \[HIGH] * Title vs sidebar semantics. The frontmatter `title` **MUST** be context-free and self-describing for search and deep links; the `sidebarTitle` **SHOULD** be concise and rely on the current navigation context. One-word generic titles (e.g., “Overview”, “Introduction”) **MUST NOT** be used as `title` except on top-level pages (`/the-page`) or when the page is a proper name/term (e.g., “Tonkeeper”, “TON Center”). In those cases, a one-word `title` **MAY** be used. Otherwise, the `title` **SHOULD** replicate or expand the section/folder name (e.g., “Sharding overview”), and the `sidebarTitle` **MAY** be “Overview”. (Why: descriptive titles improve discoverability and stand alone; short sidebar labels read better in context.) Example ```mdx --- title: "Sharding overview" sidebarTitle: "Overview" --- ``` Example ```mdx --- title: "How to get testnet Toncoin" sidebarTitle: "Get testnet Toncoin" --- ``` ### 16.4 Links and anchors [#164-links-and-anchors] * Internal links **MUST** be root-absolute (start with `/`) and **MUST NOT** include `./` or `../`; ensure anchors are stable. (Why: root-absolute links survive file moves and changes to the information architecture; relative segments break during reorganizations.) \[HIGH] * Trailing slashes: Follow a single repo-wide policy set by the site generator, and apply it consistently across all internal links. (Why: consistency prevents duplicate routes, cache misses, and SEO issues.) * Cross-section links **SHOULD** target specific anchors rather than page tops. (Why: deep links land readers directly on the needed detail.) ### 16.5 Status labels [#165-status-labels] * Pages and features **MAY** declare a status in content at the top of the page using an `` with a clear title (e.g., `title="Deprecated"` or `title="Experimental"`). Do not introduce custom frontmatter keys for status. (Why: status is visible to readers and does not require unsupported metadata.) * If deprecated, the page **MUST** include the replacement (link to successor) and the removal timeline (date or version) in the callout. You **MAY** set `noindex: true` in frontmatter to exclude the page from search when appropriate. (Why: clear migration guidance reduces breakage; de-indexing avoids surfacing outdated pages.) * If experimental, briefly state scope and limitations; link to the stable alternative when available. (Why: scope limits misuse and points to the dependable path.) * Status labels (experimental/deprecated) are independent of safety callouts (see [§11](#11-safety-critical-content-blockchain-specific)). Apply both when applicable. (Why: status communicates lifecycle; safety communicates risk—readers need both.) ### 16.6 Components used in content [#166-components-used-in-content] * On normal documentation pages, **SHOULD NOT** use `` components; prefer headings, lists, and inline links for navigation and structure. (Why: cards add visual chrome that is rarely needed for comprehension.) * Existing `` usages **SHOULD** be confined to top-level index or overview pages where the card layout clearly improves navigation. Over time, simplify or remove cards that do not provide a clear navigation benefit. (Why: keeping cards to a few deliberate entry pages avoids fragmenting the visual style.) * When an index-style page genuinely needs card-like tiles, you **MAY** use ``; keep the content inside each card minimal and avoid duplicating information from the linked pages. (Why: cards should support navigation, not introduce a second layer of prose.) * More generally, follow the “minimal styling” workflow from [§6.2](#6-2-quotation-marks-and-emphasis): components such as ``, ``, ``, or tab containers **SHOULD** appear only when they improve comprehension or navigation, not as decoration. (Why: reduced decorative chrome makes structure and behavior stand out.)
## Content hygiene and timeless writing [#17-content-hygiene-and-timeless-writing] Objective. Reduce staleness, duplication, and maintenance costs. (Why: fresh, non-duplicated content is cheaper to maintain and more trustworthy for readers.) ### 17.1 Single source of truth [#171-single-source-of-truth] * Each fact **MUST** have a canonical home. If you need the same fact elsewhere, link to it (see [§12](#12-links-and-cross-references)). (Why: one source prevents contradictions and simplifies updates.) * Guides **MUST NOT** replicate reference tables; summarize and link. (Why: duplicated tables drift and become incorrect.) ### 17.2 Timelessness [#172-timelessness] * You **SHOULD NOT** use words like “currently”, “new”, or “soon”. (Why: time-relative words stale quickly and lose meaning.) * Prefer durable phrasing: “Since v2.3, X is supported,” not “newly added.” (Why: version-based phrasing stays accurate over time.) * Remove version qualifiers once they’re no longer useful. (Why: eliminates outdated noise and keeps prose evergreen.) ### 17.3 Freshness and updates [#173-freshness-and-updates] * When behavior changes, the relevant pages **MUST** be updated promptly. (Why: outdated steps cause failures and support load.) * Large refactors **SHOULD** include redirects and update cross-links. (Why: preserves deep links and prevents 404s.) * Avoid re-documenting external tools; link to official docs and focus on TON-specific usage. (Why: external details change often; linking reduces churn.) ### 17.4 Proofread [#174-proofread] * Read aloud or skim with a “scanner’s eye”; long sentences **SHOULD** be split (see [§8](#8-readability-and-scannability)). (Why: catches awkward phrasing and improves scannability.) * Check terms against the term bank; enforce casing and spelling consistently. (Why: consistent terminology improves comprehension and search.) Rationale: “Timeless” style and a canonical home for facts keep the docs trustworthy and maintainable.
## Style exceptions and edge cases [#18-style-exceptions-and-edge-cases] Objective. Provide a controlled escape hatch without eroding consistency. (Why: limited, trackable exceptions solve real edge cases without letting the style drift.) * Any deviation from this guide **MUST** document: the rule being overridden, the reason, the scope (pages affected), the owner, and an expiry or review date. (Why: documentation, ownership, and a sunset make exceptions accountable and reversible.) * Exceptions **SHOULD** be rare, time-boxed, and revisited. (Why: scarcity prevents precedent; time limits force cleanup.) * For audience-critical reasons (e.g., highly advanced research notes), a page **MAY** relax sentence-length norms ([§8](#8-readability-and-scannability)) or include extra theory in a how-to ([§3](#3-documentation-framework-content-types)), but the page **MUST** clearly state the rationale at the top (e.g., Audience: Advanced). (Why: transparency lets readers self-select and prevents surprise.) * When quoting external code or configuration verbatim for legal or technical reasons, formatting **MAY** violate some house rules if changing it would misrepresent the original. Such cases **SHOULD** be rare and, for large or recurring examples, **SHOULD** be documented as style exceptions with scope and owner. (Why: fidelity to external sources sometimes takes priority over local formatting rules.) * A safety requirement ([§11](#11-safety-critical-content-blockchain-specific)) **MUST NOT** be waived. (Why: reader safety outweighs convenience.) \[HIGH] Rationale: Exceptions exist to serve clarity, not convenience. They are documented so future editors can normalize them later.
## Appendices [#19-appendices] ### A. Admonition levels and usage [#a-admonition-levels-and-usage] Use the least severe callout that communicates the point; overuse reduces impact. (Why: calibrated severity keeps important warnings noticeable; overuse leads to alert fatigue.) Implementation. Render callouts with the `` component (see `/src/components/mdx/callout.tsx`). **MUST NOT** use Markdown blockquotes (`>`) to simulate callouts. The only supported `type` values are `note`, `tip`, `caution`, and `danger`. Map levels to types: Note → `type="note"`; Tip → `type="tip"`; Caution → `type="caution"`; Warning → `type="danger"`. Use `title` to set the visible label when needed (e.g., `title="Important"`). (Why: consistent components and a fixed type set keep callouts accessible and visually coherent.) \[HIGH] * On pages with multiple hazardous actions, combine a page-level safety `` at the top (describing overall risk, scope, rollback/mitigation where feasible, and environment) with short local `` elements near each dangerous step that can refer back to the summary instead of repeating it. (Why: the combination keeps risks visible without duplicating long warnings at every step.) | Level | When to use | MUST include | | --------- | -------------------------------------------------------- | ----------------------------------------------- | | Note | Auxiliary info or minor edge cases | Short, actionable text only | | Tip | Productivity boosters, shortcuts | A clear benefit (“Saves time by …”) | | Important | Prerequisites, state assumptions, gotchas | The condition and its effect | | Caution | Potential data loss or non-recoverable state | Risk + mitigation/rollback | | Warning | Security, funds/keys/validator risk, chain-affecting ops | Risk + scope + rollback + testnet/mainnet label | (Why: the “MUST include” fields ensure every callout contains the minimum information a reader needs to act safely.) Examples * Important — prerequisite “This guide requires a funded testnet wallet.” * Caution — data loss “`--purge-ledger` removes local data. Back up `` before running.” * Warning — funds at risk “Transfers on mainnet are final.” * Warning — page with many risky steps “Read the safety note at the top of this page before running any mainnet commands.” (Admonition usage aligns with the safety requirements in [§11](#11-safety-critical-content-blockchain-specific).) ### B. Banned and preferred terms [#b-banned-and-preferred-terms] Use this list in combination with the project term bank (see [§13](#13-terminology-and-naming)). Editors **MUST** expand it over time. (Why: the lexicon evolves; keeping it current prevents drift and inconsistency.) Filler/tone (ban outright) (Why: filler adds no information and can sound condescending.) * Banned: simply, just, obviously, clearly, please note, super-, ASAP * Use instead: omit or state the concrete action/effect Marketing/promotional (ban outright) (Why: marketing language erodes trust, adds no actionable information, and ages poorly.) * Banned superlatives: blazingly fast, revolutionary, world-class, seamless, best-in-class, powerful, cutting-edge, game-changing, next-generation * Banned vague adjectives (without measurable criteria): reliable, robust, essential, elegant, intuitive, flexible, comprehensive, scalable, efficient, optimal, superior * Banned dramatic/emotional words: elusive, challenging (as drama), painful, frustrating, nightmare, perfectly, beautifully, amazing, incredible, stunning * Banned intensity words: instantly (unless literal), immediately (unless literal), extremely, incredibly, massive, huge (for non-quantified values) * Banned storytelling openers: "Imagine…", "Picture this…", "Have you ever…", "What if…" * Use instead: measurable facts, specific numbers, concrete conditions, or omit entirely Inclusivity (Why: inclusive terms are clearer for everyone and avoid excluding readers.) * Banned: whitelist/blacklist → Preferred: allowlist/denylist * Banned: master/slave → Preferred: primary/replica (or leader/follower, depending on context) * Banned: sanity check → Preferred: basic check / smoke check * Banned: dummy value → Preferred: sample value / placeholder * Banned: crazy/insane → Preferred: unexpected / invalid Clarity (Why: simpler words are read and translated more reliably.) * Avoid: utilize → Use: use * Avoid: prior to → Use: before * Avoid: in order to → Use: to * Avoid: leverage (as verb) → Use: use/apply * Avoid: handle → Use: process/manage (be specific) TON-specific casing (selected; see [§13](#13-terminology-and-naming) for more) (Why: exact casing improves search, recognition, and copy/paste fidelity.) * Correct: TON, TON Mainnet; smart contract; bag of cells; BoC; accountchain, shardchain, workchain, masterchain, basechain; ZK-proof, ZK-rollup. * Incorrect: Ton; ton mainnet; Smart Contract; BOC; ShardChain; Shard Chain; WorkChain.