ITADN · 发现全球开源项目

如果您希望提供 HTML 版本的速查表，请创建一个 Pull Request，在此仓库的 html/ 目录中添加一个新的 .qmd 文件。使用其中一个现有的 qmd 文件作为起点/模板。这些文件不应是 PDF 版本的重复——它们应该是基于文本的，以便对视力障碍人士更具可访问性。应尽量减少使用图像，任何图像都应包含适当的替代文本。

Tips for making a new cheatsheet

速查表并非用于文本或文档！ 它们是可通过扫视获取的视觉辅助工具，利用布局和视觉助记符帮助人们快速定位所需的功能。请将速查表视为快速参考，重点在于“快速”。这里有一个类比：

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

你的速查表中的所有内容都应设计为引导用户_快速_获取关键信息。如果你只是在总结文档手册，那就做错了！以下是一些帮助你正确操作的提示：

入门

RStudio 速查表托管在 https://github.com/rstudio/cheatsheets。你可以通过拉取请求（pull request）向该仓库提交新的速查表。请参阅贡献指南以获取更多信息。
文件 keynotes/0-template.key 和 powerpoints/0-template.ppt 是包含一些有用提示的官方模板。
你可能发现，通过复制最近的 Keynote / Powerpoint 速查表并进行大量编辑来创建新的速查表是最简单的方法——我就是这么做的！

流程

请预留比预期更多的时间来制作这些表格。到目前为止，我发现以下流程耗时最少：

确定要包含哪些函数，方法是阅读包的网页和 vignettes。我尽量将速查表限制在基本内容上。
组织函数 为有意义、自解释的分组。每个分组应解决一个共同的问题或任务。
思考如何可视化每个函数的目的。 视觉助记符比文本更容易浏览，因为文本看起来都差不多。
思考除了函数之外，速查表还应包含哪些关键心智模型、定义或解释。理想情况下，使用这些来解释可视化内容。
草绘几种可能的布局 用于该表。注意将更基础的和/或前置内容放在其他内容的上方和左侧。尽量将相关内容保持在页面的同一侧。通常，你最终的布局本身就会成为该速查表主题的“心智地图”。
输入所有计划包含的解释和函数描述。 将它们布局好。为可视化内容使用占位符。验证所有内容是否都能容纳。空白非常重要。使用它使表格易于浏览并隔离内容分组。保留空白，即使这意味着文本更小。
制作可视化内容。 它们耗时最长，所以我将其留到最后，或者在执行第 6 步时制作。
调整直到满意。

视觉设计

使用你在速查表中看到的现有主题。 它具有一致性，且适合黑白打印。
选择一种高亮颜色 在整个速查表中使用，并在右上角背景中重复使用此高亮颜色。理想情况下，你可以找到一种与其他速查表足够不同的颜色，这样在翻阅速查表小册子时，你可以快速区分出你的速查表。
谨慎使用或完全避免使用第二种颜色 以吸引注意力到需要的地方，并区分不同的内容分组。
包含大量空白。
在视觉上区分内容组。 背景、方框、侧边栏和标题在这里很有帮助。用户能够立即知道一组内容从哪里开始和结束是非常有用的。我们的“渐变标题”在这里失败了，所以如果可能，请想出更好的解决方案。
对齐事物 到参考线，即跨页对齐事物。这有助于定义空白，并使速查表更加有序和专业。
文本不要小于 ~10pt。
如果字母是白色且背景为彩色，使字体更粗 - 半粗体或粗体。
保留粗体文本 用于简单、重要的陈述，或引导扫描的眼睛到重要的单词，例如标识讨论主题的单词。不要将整个段落设为粗体文本。

内容

包含一个十六进制贴纸、IDE 截图或其他品牌材料。速查表具有作为营销材料的第二功能。
包含一个 Creative Commons 版权，以便轻松分享该表格。你会在每个速查表和模板中找到一个内置的。
务必非常简洁 - 尽可能依赖图表。
注意细节！ 你的读者肯定会注意……所以务必准确。
如有疑问，就省略。 毕竟还有文档手册。
代码注释能传达信息，但无法 吸引读者的注意力。对于重要信息，最好使用箭头、对话气泡等。如果不是重要信息，就省略。
简单可用的示例比文档细节更有帮助。 它们针对用户的痛点，展示代码，并提醒用户如何运行，同时最大限度地减少上下文切换。
添加一些简洁的文字，帮助用户理解你的章节和图表。图片最好，但读者需要能够解读它们。

摘要

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

速查表完全属于_面向人类的软件设计_范畴。它们关注的是人类的注意力。这意味着什么？当你编写文档时，你的任务是补充所有相关的细节——这是一项面向软件的工作，你需要了解软件才能做到这一点。你假设感兴趣的人会自行找到你的细节（并在找到时理解它们！）。当你制作速查表时，你的任务发生了反转。你假设相关细节已经存在于文档中。你的任务是帮助感兴趣的人找到并理解它们。你的任务是引导人类的注意力。不要只是写作，要设计。

网站

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

我们更倾向于让 Quarto 速查表在 execute 选项中设置 eval: true 和 output: false（而非 eval: false），因为这有助于确保其中的代码在重新运行时仍然有效。可以按代码块（chunk）为单位做出例外，有些（例如 keras）由于安装复杂，实际上并不总是可行运行。