笔记本是更好的自述文件

很多时候，要求开放源码项目的新手在做任何实际工作之前先为自述文件或文档做贡献。开始新工作也是一样。许多较小的项目在事后都会准备好自述文件。我们也倾向于忘记保持自述文件/文档的最新状态，从而使它们更加混乱。

我已经写了一年多的项目，希望能得到帮助，支持和协作。然后，我意识到自开始以来就没有更新我的自述文件，但它已经过时了，坦率地说很烂。这并不令人信服，这是开发人员评估我的项目时首先看到的东西！

这段引文来自于有关自述驱动开发的Hacker News主题（顺便说一句，敬请阅读！）。该名称意味着您应在编写任何代码之前先编写自述文件。我想将这个想法扩展到浏览器内部的工作。

如果读者可以与代码交互，在遵循文档的一般叙述的同时尝试不同的模式和值，该怎么办？基本示例：

Draw是一个用于绘制不同颜色形状的库。它可以绘制红色，绿色和蓝色的正方形，三角形和圆形。

这种方法适用于大多数具有文本或图形输出的库。我经常发现自己安装了npm软件包，按照所有说明进行操作，只是发现它不是我所需要的。我只希望能早点学到它！如果GitHub README.md我已经在浏览器中查看了呈现的页面，那么它可以运行包代码以及正确的沙箱。

现在，GitHub提供带有Jekyll或其他静态站点生成器的GitHub Pages，但我在这里看到两个主要缺点：

GitHub自述文件的优点在于，它们在外观和感觉以及内容上在一定程度上是绝对一致的。为了说明问题，请看一下Prism.js＆＃39; GitHub页面。 （我喜欢图书馆，但无意以任何方式挑选它）。我试图通过上面的import语句找到如何突出显示DOM节点，但是该页面让我立刻感到很难找到所需的内容。相反，我什至想在打开页面之前就知道要看哪里。应该注意的是，设置静态站点生成器是额外的工作，很多人都不愿意并且能够做。

另一方面，我认为他们的README.md缺少支持或GitHub Pages网站。

Prism是一个轻量，健壮和优雅的语法高亮库。这是Dabblet的一个衍生项目。

没有编写这种自述文件/文档页面的标准方法。我们并不总是拥有README.md和GitHub Flavored Markdown，但是今天它是一种商品，没人注意到它以非常低的成本为维护者带来了改进。

现在，我一直在研究一种将笔记本，电子表格和“ app-builder”组合在一起的工具。这是一种类型，与上面描述的需求相去甚远，那天我发现自己正是以这种方式编写自述文件！您现在正在阅读的页面是Markdown，具有额外的语法。看一下这个：

// Prism.jsTheme的演示代码：{theme = select（{value：＆＃34; prism＆＃34;，options：themes}）} {applyTheme（theme）} String：{value = input（{value：＆＃ 39; const pyramidjs = test === 42 || 43＆＃39;，大小：4}}}输出：{高亮（值）}

花括号内的表达式是电子表格单元格，因此其状态的任何更改都将应用于任何依赖的节点。就像没有网格和地址的Excel。 select和input函数是围绕html select和input标签的简单包装器，而Highlight是Prism.js包装器组件。您正在读取的该文件是index.md，根据Ellx约定，它与index.js共享作用域，因此所有提及的功能都由它导出。

这些很少的想法结合在一起，为编写自述文件和编写库代码提供了一种非常简洁的方法。随着开发的进行，自述文件中记录了开发过程时，它就变成了即时TDD。最近我尝试了这种方法。首先，描述意图，就像在测试中一样添加演示代码。

然后添加控件来玩耍，搜索边缘情况或与其他功能组合。冲洗并重复。 （实际上发现了单行求和函数🤦‍♀️中的错误）

{a =输入（{类型：＆＃34; number＆＃34 ;，标签：＆＃34; a＆＃34 ;，值：1}）} {b =输入（{类型：＆＃34; number＆＃34; ，标签：＆＃34; b＆＃34 ;，值：2}}} {c =输入（{类型：＆＃34; number＆＃34 ;，标签：＆＃34; c＆＃34 ;，值：3} ）} {a} + {b} + {c} = {mySum3（a，b，c）}}

最重要的是，自述文件正在执行与共享库共享的代码，而不是发布到npm的最新版本。这将自述文件变成其代码的功能，从而至少使执行的代码部分保持最新。

如果您对您的项目或库的这种自述文件感兴趣，请自己尝试，加入Discord，或在[email protected]上与我联系！