技术写作与文档2022quarto.org
Quarto：基于 Pandoc 构建的科技出版系统
Quarto: A scientific and technical publishing system built on Pandoc
导读
Quarto 是基于 Pandoc 的科学与技术出版系统，能把同一份源文件输出为 HTML、PDF、Word、ePub 等多种格式。对写作者来说，它讨论的不只是排版工具，而是内容与呈现分离、成果可复现且可检查的写作流程。需要写技术文档、论文或书稿的人值得一读。
可以直接用的写作要点
- 01
把内容写在纯文本源文件里，用同一份稿子生成网页、PDF、Word 等多版本，避免多平台重复维护。
- 02
将数据、代码、变量与正文分离，例如用独立变量文件，换一套数据或参数即可复用同一篇稿子。
- 03
让读者能追溯到数据与代码，甚至点击查看或修改源笔记本，提高技术写作的可信度和可复现性。
- 04
选择对表格、代码块和语法检查支持更好的写作环境，减少手动拼格式的摩擦，把精力放在表达上。
HN 评论精选
发表物应是可检查、可修改流程的一个输出子集，而不是终点。
非常有意思！为了可复现研究，我大学时曾用一份包含数据和代码的 R Studio 源文件做出交互式可视化，并输出多种结果（嵌入 R notebook 的 HTML、Markdown、Word、PDF……）。技术上很简单，但带来了很有用的场景：我可以把作业以易读格式发给教授；如果他想深入检查，也能确认我每一步做对了，还能改数据看是否仍能运行——用 HTML 文件，他只需点底部的源 notebook 就能开始调整。如果科学出版能走向这种模式——发表物只是一个人人都能检查和修改的流程的子集（比如 Word 输出）——那就太好了。当然，数据集正成为最重要的原料，我担心这还要很久。顺便说，动态示例在我的 Edge 浏览器里打不开。
csdvrx查看英文原文
Very interesting! For replicable research, in uni I once built interactive visualizations from a R studio source that contained the data + the code but that resulted in multiple outputs (html embedding the R notebook and markdown files, Microsoft Word, PDF...) Technically, it was quite simple, but it enabled interesting usecases: I could send my homework to my professor in an easily readable format, but if he wanted to dig deeper, he could also check I did everything right, and he could also alter the data to check if it kept working: using the html file, he just had to click to the source notebook at the bottom to start tweaking. It would be wonderful if scientific publishing moved to something like that, where the publication would be a subset (ex: Word output) of a process that everyone could inspect and alter. Of course, as datasets are becoming the most valuable ingredient in a big soup, I fear this will take a while to happen. BTW op: your dynamic examples like https://htmlpreview.github.io/?https://github.com/quarto-dev/quarto-gallery/blob/main/articles/html/html.html are not working in my browser (Edge)
把 YAML 和变量从正文中分离，换参数时不用改源稿。
相关可看我写的 Typesetting Markdown 系列（跳到后面部分可看到 R 和注释）。我一直在做一个编辑器，可以插值字符串变量来替代那些脚本。很多 Markdown 出版系统把 YAML 头放进 Markdown 文档，感觉像把呈现和内容混在一起。用 KeenWrite 可以这样：keenwrite -i filename.Rmd -o filename.pdf -v variables.yaml。意思是，想换一组值，你可以提供另一个文件，而不必修改 R Markdown 源文件。当然，你也可以写 shell 脚本在处理前拼接 YAML 头。
thangalin查看英文原文
Of related interest is my Typesetting Markdown series (skip to the later parts to see R and annotations): https://dave.autonoma.ca/blog/2019/05/22/typesetting-markdown-part-1/ I've been working on an editor that can interpolate string variables to replace those scripts: https://github.com/DaveJarvis/keenwrite/blob/master/docs/screenshots.md Many Markdown publishing systems put YAML headers into Markdown documents, which feels like mixing presentation with content. With KeenWrite you can do: keenwrite -i filename.Rmd -o filename.pdf -v variables.yaml Meaning, if you wanted to apply a different set of values, you can supply a different file, without having to modify the R Markdown source. (Of course, you can always write shell scripts to concatenate the YAML header prior to processing.)
多格式输出（PDF、ePub）是技术书写作工具的关键能力。
由于 mdBook 无法生成 PDF 或 ePub 等格式，我们把书从 mdBook 迁到了 Quarto。目前运行良好，做得很棒！
xvilka查看英文原文
We have moved our book from mdBook to to the Quarto due to the inability[1][2] of mdBook to produce formats like PDF or ePub. So far it works well, amazing job! [1] https://github.com/rust-lang/mdBook/issues/88 [2] https://github.com/rust-lang/mdBook/issues/815
写作工具应降低表格和代码插入的摩擦，并复用熟悉的编辑器与语法检查。
这看起来很棒。我排版文档时最大的两个痛点是：1. 插入表格和代码异常困难。谁想手动复制粘贴数字，还要插入一堆不透明的竖线、& 和其他神秘符号。2. LaTeX 的编辑器插件相当一般。在 Markdown 里，我可以用现有文本编辑器的插件生态，包括高级语法检查工具。
lumost查看英文原文
This looks brilliant. My two biggest pain points with authoring typesetted documents are 1. Inserting tables, and code is unreasonably difficult. Who wants to copy/paste numbers manually while inserting an opaque set of pipes ampersands and other arcane symbols. 2. Editor plugins for latex are pretty lackluster. In markdown I can use my existing text editors plugin infrastructure including premium grammar checking tools.
同类还值得读
编写更好文档的框架
A Framework for Writing Better Documentation
这是 Divio 的文档写作框架，把技术文档按「读者的目标」分成四类：教程（学习导向）、操作指南（问题导向）、参考（信息导向）、解释（理解导向）。
技术写作与文档2021 · 637 分 · 76 评4 条写作要点编辑精选写好一份设计文档
Writing a good design document
这篇 HN 帖子标题为《Writing a good design document》，主题是如何写好一份设计文档；对写作者来说，它值得作为技术写作和结构化说明文的参照。
技术写作与文档2025 · 581 分 · 147 评3 条写作要点编辑精选技术写作课程
Technical Writing Courses
这是 Google 官方免费技术写作课程（两门），讲受众定义、主动语态、短句、文档结构等基础方法。
技术写作与文档2020 · 571 分 · 73 评4 条写作要点编辑精选写出更好的错误信息
Write better error messages
这篇帖子讨论如何写出更好的错误信息，评论补充了开发者场景下的具体做法和真实反面案例。
技术写作与文档2022 · 566 分 · 253 评4 条写作要点编辑精选写一本技术书的经济账
The Economics of Writing a Technical Book
一位技术书作者拆解写书的真实经济账：版税收入往往远低于投入的时间成本。
技术写作与文档2018 · 519 分 · 149 评4 条写作要点编辑精选