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.