cheatsheets

Posit 速查表

速查表使学习和使用我们最喜欢的一些软件包变得容易。它们以各自的PDF版本发布在这里：https://posit.co/resources/cheatsheets/，有些也可以在RStudio IDE的"帮助 > 速查表"中找到。

我们也开始以更易访问的基于文本的HTML格式提供一些速查表。这些可在 https://rstudio.github.io/cheatsheets/ 找到。

此存储库包含当前版本、存档版本和翻译版本的源文件。

速查表使用知识共享版权。更多详情请参阅LICENSE文档。

翻译

如果您希望通过翻译速查表来为这项工作做出贡献，请随意使用源Keynote文件。要提交翻译，请通过GitHub使用拉取请求。更多信息请参阅贡献指南。

HTML速查表

如果您希望提供HTML速查表版本，请创建一个包含新.qmd文件的拉取请求，将其放在此存储库的html/目录中。使用那里现有的qmd文件作为起点/模板。这些不应该是PDF版本的复制品 - 它们应该基于文本，以便对视障人士更加友好。应尽量减少图片的使用，任何图片都应包含适当的替代文本。

制作新速查表的技巧

**速查表不是文本或文档！**它们是可扫描的视觉辅助工具，利用布局和视觉记忆法帮助人们快速找到所需的函数。将速查表视为快速参考，重点在于"快速"。这里有一个类比：

速查表更像是一个组织良好的计算机菜单栏，引导你找到命令，而不是记录每个命令的手册。

你的速查表的每个方面都应该旨在快速引导用户找到基本信息。如果你只是在总结文档手册，那就做错了！以下是一些帮助你正确制作的技巧：

入门

RStudio速查表托管在 https://github.com/rstudio/cheatsheets。你可以通过拉取请求向存储库提交新的速查表。更多信息请参阅[贡献指南](https://github.com/rstudio/cheatsheets/blob/main/.github/CONTRIBUTING.md)。
文件keynotes/0-template.key和powerpoints/0-template.ppt是包含一些有用提示的官方模板。
你可能会发现，通过复制最新的Keynote / Powerpoint速查表，然后进行大幅编辑来创建新的速查表是最简单的方法——这就是我的做法！

流程

制作速查表所需的时间要比你预期的多。到目前为止，我发现这个过程是最省时的：

确定要包含哪些函数，通过阅读软件包网页和说明文档。我尽量将速查表限制在最基本的内容上。
将函数组织成有意义、自解释的组。每组应解决一个常见问题或任务。
思考如何可视化每个函数的用途。视觉记忆法比文本更容易扫描，因为所有文本看起来都一样。
思考速查表除了函数外还应包含哪些关键心智模型、定义或解释。理想情况下，用这些来解释可视化内容。
草绘几种可能的布局。注意将更基础和/或先决条件的内容放在其他内容的上方和左侧。尽量将相关内容保持在页面的同一侧。通常，你的最终布局本身就是速查表主题的"心智地图"。
写出你计划包含的所有解释和函数描述。将它们排版。为可视化内容使用占位符。确认一切都适合。空白很重要。使用它来使表格可扫描并隔离内容组。保留空白，即使这意味着文字更小。
制作可视化内容。它们耗时最长，所以我把它们留到最后或在执行步骤6时制作。
调整直到满意为止。

视觉设计

使用你在速查表中看到的现有主题。它是统一的，适合黑白打印。
选择一种突出颜色在整个速查表中使用，并在右上角的背景中重复这种突出颜色。理想情况下，你应该找到一种与其他速查表足够不同的颜色，这样在翻阅速查表booklet时可以快速分辨出你的速查表。
谨慎使用第二种颜色或根本不使用，以吸引注意力到需要的地方，并区分不同的内容分组。
包含大量空白。
在视觉上区分内容组。背景、框、侧边栏和标题在这里很有帮助。对用户来说，立即知道一组内容的开始和结束位置非常有用。我们的"渐变标题"在这方面失败了，所以如果可能的话，想出更好的解决方案。
将事物对齐到参考线，即跨页对齐。这有助于定义空白，使速查表更有序和专业。
文字大小不要小于约10pt。
如果是彩色背景上的白色字母，要加粗字体 - 半粗体或粗体。
保留粗体文本用于简单、重要的陈述，或吸引扫视的目光到重要词语，如识别讨论主题的词语。不要将整个段落设为粗体文本。

内容

包含一个六角贴纸、IDE截图或其他品牌材料。速查表有第二个功能，就是作为营销材料。
包含一个知识共享版权，使表格易于共享。你会发现每个速查表和模板中都已包含这一点。
非常简洁 - 尽可能依靠图表。
**注意细节！**你的读者肯定会注意到...所以要正确。
如有疑问，就省略。毕竟有文档手册。
代码注释能提供信息，但无法吸引读者的注意力。对于重要信息，最好使用箭头、对话框等。如果不是重要信息，就省略。
简单的工作示例比文档细节更有帮助。它们在用户的痛点上与用户相遇，演示代码，并在最少上下文切换的情况下提醒用户如何运行代码。
添加一些简洁的文本帮助用户理解你的章节和图表。图像是最好的，但读者需要能够解释它们。

总结

你的速查表有两个目标。首先，帮助用户快速找到基本信息，其次，在执行上述操作时防止混淆。你最好的策略是限制放入速查表的信息量，并直观、可视化地布局这些信息。这种方法将使你的速查表同样适用于教学工具、编程工具或营销工具。

速查表完全属于软件设计的面向人类的一面。它们关注人类的注意力。这意味着什么？当你写文档时，你的工作是填写所有相关的细节——这是一项面向软件的工作，你需要了解软件才能完成。你假设感兴趣的人会自己找到你的细节（并在找到时理解它们！）。当你制作速查表时，你的工作就翻转了。你假设相关细节已经存在于文档中。你的工作是帮助感兴趣的人找到并理解它们。你的工作是引导人类的注意力。不要仅仅写作，要设计。

网站

这个存储库作为一个quarto网站部署在 https://rstudio.github.io/cheatsheets/。它使用renv来管理渲染网站所需的依赖项（特别是生成HTML速查表的html/*.qmd文件）。渲染这些速查表所需的包应列在DESCRIPTION中，以便它们能被renv::snapshot()可靠地发现。

我们更喜欢Quarto速查表在execute选项中设置eval: true和output: false（而不是eval: false），因为这有助于确保其中的代码在重新运行时仍然有效。可以根据每个代码块进行例外处理，有些（如keras）由于安装复杂，实际上不太可能一直运行。