跳到主要内容

教程样式指南

所以你决定为 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 标志。