跳到主要内容

优秀教程的原则

这些原则最初由 talkol 提出：

以下是这些要点的总结，供新贡献者参考。

原则​

  1. 整个流程应在用户的客户端上运行。不应涉及任何第三方服务。你需要做的是让用户可以简单地克隆库并立即运行它。

  2. README 应该非常详细。不要假设用户知道任何事情。如果教程需要，它还应该解释如何在你的设备上安装 FunC 编译器或轻客户端。你可以从这个文档中的其他教程复制这些内容。

  3. 如果可以，库应该包含用于合约的全部源代码，以便用户可以对标准代码进行小的更改。例如，Jetton 智能合约允许用户尝试自定义行为。

  4. 可以的话，尽量创建一个用户友好的界面，允许用户部署或运行项目，而无需下载代码或配置任何东西。请注意，这仍然应该是单独的，并从 GitHub Pages 上获取服务，以便在用户的设备上100%运行客户端。示例：https://minter.ton.org/

  5. 向用户解释每个字段选择的含义，并用最佳的例子来进行解释。

  6. 解释所有需要了解的关于安全的知识。你必须解释足够多，以便创作者不会犯错误并创建危险的智能合约/机器人/网站——你正在教他们最佳的安全实践。

  7. 理想情况下，库应该包含编写好的测试，向读者展示如何在你的教程背景下最好地实现它们。

  8. 库应该有易于理解的编译/部署脚本。用户能够只要输入 npm install 就能使用它们。

  9. 有时一个 GitHub 库就足够了，不需要写一篇完整的文章。只需一个 README，里面包含了库中你需要的所有代码。在这种情况下，代码应该有良好的注释，以便用户可以轻松阅读和理解它。