为您的开发团队创建有效的教程

对于许多团队来说，为代码库创建教程并不是一项直观的任务。怎么处理呢？怎样才能成为一个好的教程呢？我们如何正确衡量代码教程的有效性？

我们涵盖了不同公司和组织的数十个教程和方法，下面是我们发现每个代码教程都必须具备的5个元素。我们愿意更进一步地说：如果你的入门教程不符合以下标准--你可能一开始就不应该费心去创建它们。

虽然为您的工程师提供代码教程对每个人来说都可能是一项耗时的任务，但教程提供了一些固有的好处，有助于保持您的入职计划的有效性和可持续性，并提高内部知识共享的水平。

重点-只突出显示您的工程师需要学习开始使用的回购部分。如果读者需要翻阅几十个段落才能找到他们要找的东西，他们可能甚至不会费心去搜索。换句话说，教程不像你在高中写的历史论文--你在篇幅和广度上都会失分。

突出显示“为什么”。它们清楚地解释了代码背后的逻辑和/或为什么它会变成现在这样。

它们展示的是一个过程，而不仅仅是解决方案。通过查看代码的创建过程或信息流来理解代码要容易得多，而不是只看它现在的样子。

修修补补--它们提供沙盒体验或边做边学。这类似于从积压任务中抛出一个任务，因为它是实际操作的，无论它是如何构建的，并且以一种能唤起对代码库逻辑的演绎理解的方式进行指导，而且也不需要积压任务所需要的时间和投资。

最新的。他们必须是实用的，并与当前的代码保持同步。通常会扼杀好教程的是它们是否过时了。它们不仅会浪费读者的时间，而且可能会误导读者，造成实际的损害。这是许多工程师普遍不信任教程和文档的首要原因。

好的教程很难制作和维护。尽管说起来容易做起来难，但关键是让他们保持更新、专注，并鼓励独立的学习过程。下一步要调整它，将是确保我们衡量教程的有效性(在未来的帖子中有更多关于这一点的信息)，并收集反馈以随着时间的推移而改进。

对入职工程师的更多实践建议，请参见这篇文章：由Swimm的首席技术官奥默·罗森鲍姆(Omer Rosenbaum)撰写的“伪入职的终结”。

Tom Ahi Dror是Swimm的联合创始人，这是一家DevTool，帮助工程师轻松、快速地提升到任何代码库，优化团队生产力、独立工作和实现价值的时间。汤姆在目睹了工程师入职实践如何极大地影响研发效率后，与他的合作伙伴一起创建了Swimm。汤姆是以色列精英项目Talpiot的指挥官，也是ITC.tech背后的领导人之一。他拥有普林斯顿大学的公共政策硕士学位，特拉维夫大学的MBA学位和理学学士学位。希伯来大学的物理和数学专业。