跳到主要内容

教程样式指南

所以你决定为 TON 文档写一个教程?

我们很高兴你成为我们的贡献者之一!请仔细阅读以下指南,以确保您的教程遵循 TON 文档现有内容的样式和质量。

重要的是,您需要花些时间熟悉教程结构和如何使用标题。在提交自己的教程之前,请阅读我们的一些现有教程,并查看 以前的拉取请求

流程

重要

在你开始写作之前,请阅读下面的指南!它们将帮助你确保达到标准化和质量水平,这将使审查过程更加迅速。

另外,请参考我们提供的示例教程结构

  1. 首先,在 GitHub 上分叉然后克隆 ton-docs 的库,并在您的本地代码库中创建一个新分支。
  2. 书写您的教程时,请牢记质量和可读性!可以查看现有教程以明确您的目标。
  3. 当准备好提交审查时,发起一个拉取请求。我们将收到通知,并开始审查过程:
    1. 请尽一切努力提交您的教程的最终稿。一些打字错误和语法修正是可以接受的,但如果在我们能够发布教程之前需要进行重大更改,审查和要求您进行必要更改的过程将会花费更多时间。
  4. 审查完您的提交后,并且您完成所有必要的更改后,我们将合并拉取请求并在 TON 文档上发布教程。此后不久,我们将与您联系安排付款!
  5. 发布后,记得在社交媒体上推广您的教程!文档维护者可以帮助扩大这种推广,只要您与我们合作。

总而言之,工作流程如下:

  1. 分叉并克隆 ton-docs 代码库
  2. 编写并润色 您的教程
  3. 提交拉取请求 进行审查
  4. 进行其他必要的更改
  5. 教程 合并并发布
  6. 在社交媒体上推广您的教程

背景

在 "TON" 前加上 "THE" 的主要问题是,在开发 TON 文档和政策编辑期间,市场营销、供应商和开发人员等多个部门加入了讨论,以大写 "Blockchain"、"Ecosystem" 等词汇与 "TON" 结合使用,以创建一个单一系统、网络和品牌的强大形象。经过长时间的讨论,我们得出结论,为了推出强大的品牌形象,我们应该创建一个词汇和短语表,可以不使用 "THE" 并大写书写。如果可以大写,就不需要冠词。目前有两个这样的词组:TON Blockchain 和 TON Ecosystem。

对于其他 TON 模块名称,如 TON Connect、TON SDK、TON Grants等,取决于上下文。我们应用大写规则,但对于冠词规则则较为灵活。如果组件名称单独存在,最好不用冠词。然而,如果它与普通名词结合,如 TON Connect protocol,则需要冠词,因为它指的是实体协议。

至于其他词组,如 "TON + 名词"(例如,"the TON world"、"the TON community" 等),我们不限制使用冠词,因为我们期望能看到这样的一个结合。

一般提示

  • 不要复制粘贴现有内容。剽窃是一个严重的问题,我们不会容忍。如果教程受到现有内容的启发,请给出参照并链接到它。链接到其他教程/资源时,请尽可能使用 TON 文档的资源。
  • 在 PR 中包含演示视频或视频内容,方法是上传到 Google Drive。
  • 必须清楚地解释如何从水龙头获得账户资金,包括哪个账户能拿到资金,从哪里,以及为什么。不要假设学习者可以自行完成这项任务!
  • 显示示例输出,以终端片段或屏幕截图的形式,以帮助学习者了解预期效果。记得要修剪长输出。
  • 采取错误驱动的方法,故意遇到错误,教学习者如何调试。例如,如果您需要注资一个账户才能部署合约,请先尝试在不资助的情况下部署,观察返回的错误,然后修复错误(通过注资账户)并再次尝试。
  • 添加潜在的错误和故障排除。当然,教程不应列出所有可能的错误,但应努力捕捉重要的或最常见的错误。
  • 使用 React 或 Vue 进行客户端开发。
  • 在提交 PR 之前,首先自行运行代码,以避免其他明显的错误,并确保其按预期工作。
  • 避免在教程之间包含对不同来源的外部/交叉链接。如果您的教程较长,我们可以讨论如何将其变成更长的课程或路径。
  • 提供图片或截图 来说明复杂过程,如有需要。
  • 将您的图片上传到 learn-tutorials 库的 static 目录——不要 使用外部网站的热链接,因为这可能导致图片损坏。
  • 图片链接必须以 markdown 格式呈现,您 只能 使用库中 static 目录的原始 GitHub URL:![您图片的名称](https://raw.githubusercontent.com/ton-community/ton-docs/main/static/img/tutorials/<您图片的文件名>.png?raw=true)
    • 记住在 URL 的末尾添加 ?raw=true

如何构建您的教程

示例教程结构

您可以随时查看示例教程结构进行了解。

  • 标题 应该直接明了,概括教程的目标。不要在文档内以标题形式添加教程标题;而应使用 markdown 文档文件名。
    • 例如:如果您的教程标题为"Step by step guide for writing your first smart contract in FunC",文件名应为:\ step-by-step-guide-for-writing-your-first-smart-contract-in-func.md
  • 包含一个简介部分,用来解释为什么这个教程很重要,以及教程的背景是什么。不要假设这是显而易见的。
  • 包含一个必要条件部分,用来解释任何要求预先掌握的知识或需要首先完成的其他现有教程,其他所需的代币等。
  • 包含一个要求部分,用来解释在开始教程之前必须安装的任何技术程序,以及教程不会涵盖的内容,如 TON 钱包扩展、Node.js 等。不要列出教程中将安装的包。
  • 使用子标题(H2: ##)来分构教程正文。使用子标题时要记住目录,并尽量保持重点。
    • 如果子标题下的内容很短(例如,只有一个段落和一个代码块),考虑使用加粗文本而不是子标题。
  • 包含一个结论部分,总结所学内容,强化关键点,同时也为学习者完成教程表示祝贺。
  • 可选)包含一个接下来部分,指向后续教程或其他资源(项目、文章等)。
  • 可选)在最后包含一个关于作者部分。您的简介应包括您的 GitHub 个人资料链接(将包含您的姓名、网站等)和您的 Telegram 个人资料链接(以便用户可以联系/标记您,从而获得帮助和提问题)。
  • 如果您在编写此教程时参考了其他文档、GitHub 库或其他教程,必须 存在一个参考资料部分。可实现的话,就通过添加他们的名称和文档链接来致谢(如果不是数字文档,请包括 ISBN 或其他参考方式)。

样式指南

  • 写作措辞 - 教程由社区贡献者为他们的同行撰写。

    • 鉴于此,我们建议在整个教程中创造一种包容和互动的语调。使用“我们”、“我们的”这样的词语。
      • 例如:"我们已经成功部署了我们的合约。"
    • 提供直接指导时,可以自由使用“你”、“你的”等。
      • 例如:"你的文件应该看起来像这样:"
  • 在您的教程中正确使用 Markdown。参考 GitHub 的 markdown 指南 以及 示例教程结构

  • 不要使用预格式化文本进行强调例如

    • ❌ "TON 计数器 智能合约 名为 counter.fc" 是不正确的。
    • ✅ "TON 计数器 智能合约 名为 counter.fc" 是正确的。
  • 不要在节标题中使用任何 markdown 格式例如

    • ❌ # 简介 是不正确的。
    • ✅ # 简介 是正确的。
  • 解释你的代码! 不要只让学习者盲目地复制和粘贴。

    • 函数名称、变量和常量 必须 在整个文档中保持一致。

    • 使用代码块开头的注释来显示代码所在的路径和文件名。例如

      // test-application/src/filename.jsx

      import { useEffect, useState } from 'react';

      ...
  • 选择合适的语言 用于代码块语法高亮!

    • 所有代码块 必须 有语法高亮。如果您不确定要应用哪种类型的语法高亮,请使用 ```text
  • 不要将代码块语法用于预格式化文本例如

    • `filename.jsx` 是不正确的。
    • `filename.jsx` 是正确的。
  • 您的代码块应该有较好的注释。注释应该简短(通常是两到三行)且有效。如果您需要更多空间来解释一段代码,请在代码块外进行。

  • 记得在所有代码块前后留一个空行。\ 例如

  
// test-application/src/filename.jsx

import { useEffect, useState } from 'react';

  • 使用 linter 和 prettifier 在将代码粘贴到代码块之前。对于 JavaScript/React,我们推荐使用 eslint。对于代码格式化,请使用 prettier
  • 避免过度使用项目符号、编号列表或复杂的文本格式。使用 粗体斜体 强调是允许的,但应保持最少。

应用设置

  • Web3 项目通常会包含几个现有的代码库。编写教程时,请考虑到这一点。在可能的情况下,提供一个 GitHub 库作为学习者入门的起点。
  • 如果您使用 GitHub 库来包含教程中使用的代码,请记得向读者解释如何创建文件夹以保持良好的代码组织。 例如mkdir example && cd example
  • 如果使用 npm init 来初始化项目目录,请解释提示或使用 -y 标志。
  • 如果使用 npm install,请采用 -save 标志。