Skip to main content
This guide covers the basics: how to structure pages, write examples, and keep docs consistent and safe.

​
Write for the reader

  • Default audience: experienced software developers new to blockchain. Explain TON-specific concepts. Do not re-teach general programming. This keeps pages focused.
  • Be answer‑first. Start with what the reader will achieve, what they need, and the steps. This shortens time to success.
  • Lead with a working example. Show a copy‑pasteable snippet early and the expected output. This shows it works.
  • Use a neutral, precise tone. Write in present tense, active voice, and second person (“Run the node”). This makes actions clear.
  • Keep it scannable. Use short sections and paragraphs, clear headings, lists, and tables. Most readers skim to find the next action.

​
Page types

  • Step by step — for beginners; handhold from zero to first success on one happy path; explain from scratch, define terms, and link out for depth.
  • How‑to — a focused recipe for a specific outcome; assume concepts known and show only what’s needed.
  • Explanation — concepts, architecture, and trade‑offs; clarify why and when, with minimal examples.
  • Reference — exact, complete facts (APIs, CLI, types, errors); stable anchors and minimal prose.
  • Don’t mix types on the same page.

​
Where pages go

  • Keep the flow linear; follow the docs.json sidebar.
  • In each topic group, order pages: Explanation → How‑to → Reference.
  • Canonical specs — reference/. Link to it; don’t duplicate tables or parameters.

​
Structure pages for success

  • Start with Objective and Prerequisites so readers know they’re in the right place.
  • Make each step a single action; use sub‑bullets for options.
  • Include Verify and Troubleshoot so readers can confirm success and fix common errors.
  • End with Next steps / See also only if essential (1–3 links). Prefer a linear path that needs no extra navigation.

​
Examples that run

  • Make commands copy‑pasteable. Do not include shell prompts like $ or >. Prompts break commands when pasted.
  • Separate command and output. Use two fenced blocks. Mixing them causes copy errors.
  • Use <ANGLE_CASE> placeholders in commands and prose and define each on first use (for example, <RPC_URL>). In code, use UPPER_SNAKE if < > clashes with syntax. One clear convention prevents hard‑coded values from slipping in.
  • Tag code fences with a language (bash, json, rust, and so on). This enables correct highlighting and tooling.
  • Prefer end‑to‑end examples on testnet by default. Safe defaults encourage trying the steps.
  • Label partial snippets as Not runnable and link to a full example.
  • Do not hard‑wrap long commands. Use soft wrap in the UI or safe continuation if the shell supports it. Hard wraps break execution.
Good 
ton-node start --ledger <LEDGER_DIR> --network testnet
Expected output 
Node started. Workchain: 0  Shard: -1  Status: running
Define placeholders <LEDGER_DIR> — local ledger directory. <RPC_URL> — HTTPS endpoint of your TON RPC provider.

​
Safety warnings

Add a Caution or Warning when a step moves funds, changes fees or withdrawals, exposes or stores private keys or mnemonics, modifies validator or network settings, or performs chain‑affecting operations such as resharding, pruning, halting, or replay. These actions can cause irreversible loss or outages. Pattern
Warning — funds at risk Running the next command on mainnet transfers funds irreversibly. Safer first (testnet): 
jetton transfer --to <ADDR> --amount <AMOUNT> --network testnet
If you must use mainnet: no rollback; on‑chain transfers are final.
Default to testnet in task pages. Make destructive flags opt‑in and document mitigations.

​
Necessary disclaimers

Add a Caution or Warning when a page or step:
  • Moves funds or changes fee/withdrawal behavior.
  • Exposes, stores, or transmits private keys or mnemonics.
  • Modifies validator configuration, networking, or other consensus‑affecting parameters.
  • Performs chain‑affecting operations (for example, resharding, pruning, halting, replay).
  • Uses destructive flags or commands that delete, rewrite, or lock state (for example, --purge, --force).
  • Runs on mainnet where actions are irreversible; label the environment and give safer testnet first.
Each safety callout should briefly state the risk, scope, rollback/recovery (if any), and the environment label (testnet vs mainnet).

​
Titles and headings

  • Use sentence case. Keep headings concise and unique.
  • Use imperatives for tasks (“Deploy a validator”); nouns for concepts (“Validator architecture”). Titles should signal action vs. explanation.
  • Don’t style headings, except when an identifier needs code font.
  • Use clear section labels such as Verify, Troubleshoot, and See also.
  • On first useful mention, link flags, parameters, error codes, and data types to their reference anchors.
  • Do not paste reference tables into guides. Link instead. Duplicated tables go stale.
  • Use descriptive link text, not “click here”.
  • Link core TON terms to the Glossary on first useful mention unless you define them on the page.
  • Prefer stable, relative links and precise anchors.

​
Terminology and names

  • Use the project term bank for canonical spellings, casing, and preferred terms. One vocabulary prevents drift. Examples: TON, jetton, smart contract, BoC (bag of cells), AccountChain, ShardChain, WorkChain, MasterChain, BaseChain.
  • Prefer allowlist and denylist over whitelist and blacklist. These are clearer and inclusive.
  • Use mainnet and testnet as common nouns. Use TON Mainnet and TON Testnet for the proper names. This distinguishes the generic type from the named network.

​
Files, front matter, labels

  • Filenames use kebab-case.md or kebab-case.mdx (for example, validator-setup.mdx). This is readable and consistent across platforms.
  • Optional front matter can declare doc_type, audience, and status (experimental or deprecated). If deprecated, add an Important callout with the replacement and timeline.
  • Keep sidebar labels short (2–4 words) and mirror in‑page headings.

​
Accessibility

  • Use plain English; avoid idioms and culture-specific references.
  • Use American English spelling (e.g., color, analyze).
  • Write descriptive headings and link text.
  • Tables should have headers and units (for example, “Latency (ms)”) and keep cells brief.
  • Provide text alternatives for complex figures when possible.

​
Secrets and environments

  • Never include real keys, mnemonics, or tokens. Use placeholders or clearly invalid test values. This prevents accidental leaks.
  • Prefer environment variables or keystores over inlining secrets.
  • Call out commands that can delete, rewrite, or lock state.
  • Label the environment when it matters (testnet vs mainnet).
⌘I