[论文解读] You Only Write Thrice: Creating Documents, Computational Notebooks and Presentations From a Single Source

Kacper Sokol, Peter Flach|arXiv (Cornell University)|Jul 2, 2021

Digital Humanities and Scholarship参考文献 1被引用 4

一句话总结

本文提出了一种统一的工作流程，通过版本控制的 Markdown 文件，从单一源文件生成学术文档、计算笔记本和演示文稿。通过在基于 Git 的系统中结合使用 Jupyter Book、Jupyter Notebook 和 reveal.js，该方法实现了可重现、交互式且透明的学术传播，支持端到端的版本控制与评审。

ABSTRACT

Academic trade requires juggling multiple variants of the same content published in different formats: manuscripts, presentations, posters and computational notebooks. The need to track versions to accommodate for the write--review--rebut--revise life-cycle adds another layer of complexity. We propose to significantly reduce this burden by maintaining a single source document in a version-controlled environment (such as git), adding functionality to generate a collection of output formats popular in academia. To this end, we utilise various open-source tools from the Jupyter scientific computing ecosystem and operationalise selected software engineering concepts. We offer a proof-of-concept workflow that composes Jupyter Book (an online document), Jupyter Notebook (a computational narrative) and reveal.js slides from a single markdown source file. Hosted on GitHub, our approach supports change tracking and versioning, as well as a transparent review process based on the underlying code issue management infrastructure. An exhibit of our workflow can be previewed at https://so-cool.github.io/you-only-write-thrice/.

研究动机与目标

• 解决学术产出（论文、演示文稿、笔记本、海报等）被分散为多个版本化格式的问题，这些格式难以维护且难以对齐。
• 通过将多种格式统一为单一源文件，减轻在多个格式间编写和修订内容的负担。
• 通过采用版本控制和基于问题的评审等软件工程实践，提升学术出版的透明度和可追溯性。
• 利用 Jupyter 生态系统中的开源工具，实现交互式、可执行且可访问的学术产出。
• 通过在 GitHub 等平台托管内容并集成评审工作流，支持可持续、可重用且社区驱动的学术传播。

提出的方法

• 使用扩展的 Markdown（MyST 风格）作为所有内容的单一事实源。
• 从同一源文件生成基于 Jupyter Book 的文档，以产出交互式、可执行的基于网页的文稿。
• 从同一源文件创建 Jupyter Notebook，以支持计算可重现性和实时编码。
• 从同一源文件生成基于 reveal.js 的幻灯片，用于动态、交互式的演示。
• 在 GitHub 上托管源文件，结合版本控制和问题追踪，以实现类似代码的透明化评审流程。
• 利用开源工具（Jupyter Book、Jupyter、reveal.js）确保在各种设备和平台上的可访问性、交互性和兼容性。

实验结果

研究问题

• RQ1 是否可以使用单一源文档生成多种学术输出格式——论文、笔记本和演示文稿——而无需重复或不一致？
• RQ2 如何将软件工程中的版本控制和问题追踪机制应用于学术出版，以提升透明度和可追溯性？
• RQ3 在保持可访问性和长期可持续性的前提下，交互式、可执行内容在学术产出中可集成到何种程度？
• RQ4 用动态、基于网页的出版模式替代传统的以 PDF 为中心的工作流程，会面临哪些实际挑战？
• RQ5 像 GitHub 这类社区驱动的平台，如何不仅支持代码共享，还能支持学术内容的创作、评审和传播？

主要发现

• 所提出的工作流程成功地从单一 Markdown 源文件，使用开源工具生成了三种不同的学术产出——文档、计算笔记本和演示文稿。
• 通过基于 Git 的版本控制，能够完整追踪所有修订记录，支持类似软件开发的透明且可审计的出版生命周期。
• 生成的输出原生支持交互式内容，如可执行代码块和动态可视化，显著提升了可重现性和用户参与度。
• 通过遵循网络标准并集成辅助技术（包括屏幕阅读器和导航辅助工具），确保了可访问性。
• 该工作流支持通过静态 HTML、PDF 和 EPUB 导出实现在线访问和离线浏览，确保在各种设备和平台上的广泛可访问性。
• 该方法通过在 https://so-cool.github.io/you-only-write-thrice/ 公开托管的原型实现得到验证，展示了完整工作流的实际运行效果。