Skip to main content

Documentation style guide

Introduction​

This guideline aims to help you define your audience, which will influence your content’s style and placement.

Audience​

TON Documentation (docs.ton.org) is a resource developed for three key audiences.

Concepts for individuals: Whether readers are new app users, investors, or blockchain enthusiasts, they’ll find answers to their questions about TON’s credibility, wallet capability, community engagement, and technical roadmap. Concepts simplify complex abstractions so that readers can dive in with confidence.

Guidelines for external developers: Readers can learn how to run nodes, set up sample projects quickly, and integrate their projects with TON—all presented in straightforward, step-by-step guidelines. For developers with little or no background in blockchain, this content offers a practical introduction to the TON tech stack.

Documentation for TON developers: The documentation section focuses on enhancing developer experiences through deep, detailed documentation. Here technical experts can find best practices and technical insights for developing industrial-grade smart contracts and global market applications. It is also a manual for those planning to improve blockchain software and upgrade TON protocols.

Concepts for individuals​

App users, investors, enthusiasts, or anyone new to blockchain and TON

Example individuals journeys:

  • “I want to explore TON’s credibility and, after answering some basic questions, try using it.”
  • “I know I need a TON wallet, and I want to learn how it works.”
  • “I want to get a sense of activity in the TON community, to decide if it’s active enough, so I can get help if needed.”
  • “I’m excited about TON and want to get involved, but I don’t know what to do next.”
  • “I want to learn about TON’s technical roadmap.”

Guidelines for external developers​

Example external developer journeys:

  • “I’m a developer, but I have no background in crypto and want to understand the TON tech stack.”
  • “I want to learn how to run a TON node.”
  • “I want to get a sample TON project up and running fast to get a sense of how difficult or easy it is to build a real project on TON.”
  • “I’ve started working on integrating my project to TON and want to figure out how to do this best.”

Documentation for TON developers​

Example TON developer journeys:

  • “I want to develop industrial smart contracts for TON Ecosystem according to best practice and specifications.”
  • “I want to participate in developing TON blockchain software.”
  • “I want to upgrade TON protocols to enhance the user experience.”
  • “I want to upgrade TON specification to enhance the developer experience.”

Style best practices​

This section describes best practices for concepts, guidelines, and documentation sections. Concepts and guidelines share a similar approach.

Concepts and guidelines​

These are shared content issues for readers of concepts and guidelines.

Common content issues:​

  • Overflowing with specific technical terms
  • Content inconsistency across pages
  • Articles are hard to digest due to
  • Content is too abstract and detached from reality
  • Too much text per page and paragraph
  • Usage of complex sentences
  • Too many links can overload readers, causing them to abandon the website

Make content suitable for its audience with the following rules.

Concepts and guidelines best practice​

  • Focus on the advantages for the user instead of explaining technical details about the system
  • Use active voice and clear, concise sentences that are easy to follow
  • Break up longer chunks of text into smaller sections or paragraphs
  • Consider using tables, bullet points, or numbered lists instead of paragraphs
  • Highlight (bold) key phrases to support scanning and skimming through the article
  • Limit the length of the article up to 2000 words
  • Reduce the number of hyperlinks to approximately 10 per 2000 words
  • Operate with a mindset that people just started curious about blockchain technology
  • Users want to understand how the topic relates to them and how they can take part in it rather than going deep into the theory

Documentation style​

For documentation readers, these are a list of typical content issues.

Documentation issues​

  • Inconsistencies across documentation
  • Different, unclear, and contradictory language and terminology
  • Long sentences written in passive voice
  • Outdated information
  • Only code provided, without explanation and documentation

Make content documentation great for its audience with the following rules.

Documentation best practice​

  • Provide updates on the change documentation as soon as possible.
  • Provide in-depth, clear explanations of all system components and processes.
  • Use diagrams, examples, and highlighted key points to support the text.
  • Structure content to combine thorough, on-page detail with strategic cross-references, maintaining ease of navigation without overwhelming a single page.
  • Keep content unified according to contribution guides.
  • Use active voice to craft clear, direct sentences for complex abstractions.
  • Break long sentences into shorter, simpler ones to improve readability.

Content ideas​

All section​

  • Provide visual aids to explain the topic better
  • Provide style updates and proofread

Concepts​

  • Use examples or real-life scenarios of the application of the technology to help illustrate complex concepts or ideas
  • Explain how the idea can positively affect people now or in the future

Guidelines​

  • Add step-by-step how to take action
  • Include relevant statistics or graphs to strengthen the arguments
  • Add calls to action

Documentation​

  • Update or improve existing documentation.
  • Add comprehensive new documentation about the TON Entity: node, oracle, smart contract, or TVM under the hood.

Objectivity​

TON Documentation aims to serve as a credible, neutral source of truth that informs readers about TON Ecosystem, its technology, and development. The following are examples of content that won't be accepted:

Grand, unverifiable claims about TON or adjacent technologies

  • Example: "You should buy TON for giveaways..."

Hostile or confrontational language aimed at any organization or person

  • Example: "Company X is bad because they are centralized!"

Politically charged rhetoric

  • Example: "This political party is better for decentralization because..."
warning

Any proposed content that does not align with the platform's objectives will be rejected without additional explanation. Spam and inappropriate behavior in comments will result in a ban.

Consistency​

Learn the following guides in detail, and keep content consistent.

See also​