技术写作与文档2022jstutter.netlify.app
用 groff 撰写我的博士论文
Writing my PhD using groff
导读
这篇帖子讲一位博士生用 groff 排版系统写学位论文的经历，也夹带了对 LaTeX 的吐槽（编译慢、格式化折腾、容错路径窄）。对写作者的价值在于：它把“排版工具会直接影响写作节奏与内容修改频率”这件事讲得很具体，也提供了“先用纯文本顺畅写完，再看成品效果”的实践思路。
可以直接用的写作要点
- 01
先把排版配置一次到位（宏包或样式模板），之后写作时尽量不碰格式，把精力留给内容。
- 02
优先选择编辑—预览反馈快的工具链：一旦每次查看成品都要等很久，你改句子的意愿就会被消磨。
- 03
用纯文本、接近 Markdown 的方式起草，能减少视觉干扰，让你更快进入写作状态。
- 04
别把工具当成作品：作者的教训是定制流程容易失控，要给自己设时间上限，避免本末倒置。
HN 评论精选
配置好宏之后，groff 让写作几乎不花格式化时间，编辑到预览的循环也极快。
groff 很好用。我曾有一阵子用它做工作报告，最有意思的是 W·Richard Stevens 的网站上公开了他用 groff 宏包画《TCP/IP 详解》里那些精美插图的宏；我就靠这些宏，做出了带样条曲线的漂亮图表。和我用 LaTeX 的经验相比，groff 最大的好处是：当你有一套顺手的宏之后，几乎不用再花时间调整格式；文档生成周期也很快，你可以用近似纯文本（很像 Markdown）的方式无干扰地编辑，想看成品的任何时候都能很快看到。
seanhunter查看英文原文
Groff is great. I went through a phase of doing reports for work using groff and one of the cool things is that on W Richard Stevens' website there were all his groff macros he used to produce all the beautiful diagrams in TCP/IP Illustrated etc. So I used to have lovely diagrams with spline curves etc thanks to W Richard Stevens. The great thing about groff (compared in my experience with latex) is that you spend basically zero time on formatting/messing about once you have a set of macros you like, and the document production cycle is really fast so you edit with zero distractions using basically plain text (a lot like markdown) and then any time you want to see the finished product it's very quick to see it.
LaTeX 的真正痛点在于编译慢、容错路径窄，好工具需要在可编程性和专用语法之间做艰难取舍。
文章对 LaTeX 的批评让我很有共鸣。编译时间长，加上只有一条很窄的“顺利路径”，正是 LaTeX 让我觉得效率低的地方。可惜它本来是很好的工具，尤其重视文档结构和输出质量。我正在做一个 LaTeX 的后继工具，想解决这些问题，但设计上的取舍真的很难：哪些该交给编程？哪些该通过专用语法直接暴露？结构又该如何驱动呈现？计算机排版是个无底洞，但很迷人，我相信关于它的最终结论还没出现 :)
reknih查看英文原文
The LaTeX criticisms of the article really resonated with me. Long compile times and a narrow "happy path" are the things where I feel LaTeX makes me less productive. This is a pity because, otherwise, it is a great tool with its focus on document structure and output quality. I'm currently working on a LaTeX successor which seeks to address these issues, but it is really hard to make the right design compromises here -- what can be programmed? What is accessible through dedicated syntax? How does the structure drive presentation? Computer typesetting is a rabbit hole, but a fascinating one. And I'm sure the last word on it has not been spoken yet :)
排版工具很容易让人过度投入；作者用亲身经历印证了这种定制工作流的诱惑和代价。
我很能理解作者折腾排版工作流的热情。写本科论文时，我也花了很多时间做自定义 LaTeX 模板和流程。和作者一样，痛点之一是 LuaLaTeX 这类现代引擎编辑—编译—查看的循环相对慢。我主要还在意让最终 thesis.pdf 符合 PDF/A（一种面向 PDF 长期数字保存的归档合规标准）。不出所料，我也严重跑偏了，最后还想做出完全可复现的 LaTeX PDF——对我的用例大概过头了，但确实写成了一篇记录过程的博客。
passerine查看英文原文
I can relate quite well to the author's pursuit in tinkering with their typesetting workflow. When I wrote my bachelor's thesis, I also spent a great deal of time coming up with a custom LaTeX template and workflow. Like the author, one of the pain-points was the relatively slow edit-compile-review cycle of modern LaTeX engines like LuaLaTex. In my case, I was mainly concerned with making the resulting thesis.pdf PDF/A compliant. PDF/A is a archival compliance standard that's dedicated to the long term digital preservation of PDF files. Predictably, I got way too carried away as well, and ended up trying to create fully-reproducible LaTeX PDFs as well. It was probably overkill for my use-case, but it did result in a fun blog post where I documented the process [1] [1] https://shen.hong.io/reproducible-pdfa-compliant-latex/
工具本身不是问题，关键在于按规范配置和使用；选工具时也要把版本控制这类写作流程因素算进去。
我发现，那些觉得样式不一致、大文档卡顿的人，其实是不懂怎么配置。我以前经常用 Word 写上百页报告，里面嵌 Excel、图片和公式，也相当熟练。关键要做几件事：为每种内容建具名样式，并给常用样式设快捷键；用支持免费公式编辑器的付费版本，它十年前比免费的强太多；用主文档加子文档的方式分类管理，不要把所有内容塞进一个百页文件。我确信自己当时是按工具设计的方式在使用它，并没有跟所见即所得较劲。后来我转向 LaTeX，是因为受不了 Word 在版本控制上不够方便；Word 开启修订也能做，但比不过常规工具。我也想学 LaTeX，觉得值得投入——事实证明是值得的，写公式快得多，也更好维护。所以我对 LaTeX 观感还行。现在不做数学公式了，更偏好 Markdown 或 wiki。补充：我没用过网页版，不知道它在大型文档上表现如何，应该还行，但浏览器渲染可能不太理想。
vlovich123查看英文原文
I found that those who can’t get consistent styling and have laggy behavior on large documents don’t know how to configure it. I regularly wrote hundred page reports with embedded excel and images all embedded in Word with Math and got pretty proficient. There’s basically several things you need to do: * Actually set up a named style for every type of content you have. Creating shortcuts for the common ones doesn’t hurt * use whatever the paid version that powers the free equation editor. It was miles better about 10 years ago * use a master document sub document approach for categorizing things. You wouldn’t have a single text file that’s 100 pages long. Split up Word that way too I’m pretty sure I got to a state where I was using the tooling as intended because I wasn’t actually fighting the wysiwyg. Now I did switch to LateX at the end because I was tired of not having easy version control. Word has it if you enable change tracking but it can’t beat normal tooling. Also I wanted to learn latek because it felt like a worthwhile investment (it was - writing formulas in latek is wayyy faster to write and easier to maintain). So I liked LateX just fine. Prefer Markdown / wiki these days because I don’t work with math formulas. Disclaimer: I have zero experience with the web version and have no idea how it scales. I imagine it still does quite well on large documents but maybe browser rendering is not so good.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选