可执行教程

2021-04-19 23:31:05

Permalink在构建一个大而复杂的软件项目时，您希望能够更改代码库，并确保软件仍然按预期工作。如今，人们使用自动测试来检查代码更改后的内容是否正常工作。

假设您正在努力建立某种软件应用程序的长而复杂的教程。在某些时候，您决定在教程中间改变一些东西。现在，你怎么知道你的教程仍然有效吗？经验丰富的教程作家知道，一个选择是偶尔再次通过整个教程来确保步骤仍然导致预期的结果项目。另一种选择是依赖教程的读者在进行任何更改后向问题报告问题。

具有可执行教程的想法是用户预期采取的步骤是以机器可读格式。然后，可以在任何时候执行整个教程，以确保步骤仍然导致预期的项目。

您可以在您的教程中包含步骤来单元测试您的项目。然后，如果您的项目测试通过，您可以考虑您的教程也处于传递状态。通过在测试所生成的项目，还测试了您的教程。

Udemy或Ploralsight等网站上的作者可以从首先将他们的课程作为一个可执行的教程中受益。然后，它们可以在录制视频时使用本教程作为其脚本，相信指令导致工作项目（不必一次又一次地通过手动操作）。

MVCMoviesAturntutorial是在土星构建一个简单的Web应用程序的教程。该源文件是从PowerShell编写的源文件生成的。此脚本用于将源文件转换为Marrows。

编程教程包含读者的指令，就读取器有关更改的文件以及要更改的内容。

这是MVCMoviesAturntorial的屏幕截图，它显示了如何描述文件更改的示例：

$ file =＆＃39;。\ src \ mvcmoviesaturn \ movies \ moviesmodel.fs＆＃39; $原始_text = @＆＃34;让验证器= [有趣的U - ＆gt;如果是isnull u.id那么一些（＆＃34; id＆＃34;＆＃34; id＆＃39; t为空＆＃34; t为空＆＃34;）else none]＆＃34; @ $ replyment_text = @＆＃34;让验证器= []＆＃34; @Edit $ file -replacing $ rinform_text --with $ replacement_text

如您所见，要编辑的文件名存储在变量$文件中。要替换的文本存储在$ rosific_text中。最后，新文中的$ replacement_text。然后调用编辑函数：

下一个示例是在ASP.NET核心中构建一个非常简单的链路聚合器应用程序的教程。

在本教程中，我采取了不同的方法来改变描述。我只是包括Git Diff的输出：

我认为示例1的英语更改描述在视觉上更好。但是，差异样式显然更容易创建。与前者一起，我必须手动创建每个更改描述。使用后者，我需要做的就是git diff，并在教程源中包含。

需要考虑的东西是有一种方法可以自动从Git Diff输出到更友好的样式。

Linkaggregator教程在开头包含一个屏幕截图。运行源文件时会生成此屏幕截图。

C组件，F＃Web测试框架，用于编写Linkaggregator的测试。在这些测试中，我有一步拍摄截图：

这解决了屏幕截图的问题已过期。每次运行教程源文件以测试它时，会生成新的屏幕截图。

PowerShell在Windows，Linux和MacOS上工作。因此，可以使用它可以用于编写在所有三个平台上工作的教程。

也就是说，它可能值得探索设计用于创作源文件的DSL。也许球拍或Haskell可以用于这种DSL。

在某些编程书籍中，文件更改了用户预计会通过显示整个文件来指示用户，但用户应该编辑的粗体线。向用户提供这种更改样式将是不错的。它也可能很高兴让用户达到什么样的风格;即，默认情况下显示差异样式，但允许用户按需切换到整个文件视图。

瞄准比标准Github更富有的文档格式很好，呈现了渲染的Markdown。例如，自动生成的内容表将是很好的。