技术写作与文档2021web.cs.ucdavis.edu
数学写作指南 [PDF]
A Guide to Writing Mathematics [pdf]
导读
这是一份面向选修数学课的本科生的写作指南（作者 Kevin P. Lee），评论区把它与 Halmos、Knuth 的经典写作文章联系起来，并补充了教材写作和论文写作中的实际经验。值得写作者一读，是因为它反复强调：数学写作与其他写作没有本质区别，核心都是把想法清楚地传达给另一个人；评论还提供了不少可直接迁移到各类写作的具体技巧。
可以直接用的写作要点
- 01
把“让另一个读者清楚地理解一个想法”当作唯一的核心目标，无论你写的是数学、小说还是一份组装说明书。
- 02
采用对话式的讲解语气：主动提问、预告难点并说明坚持读下去的回报，让文字像一对一的辅导。
- 03
果断精简符号与术语，必要时明确声明“为清晰起见，省略与核心思想关系不大的记号”。
- 04
避免“证明/练习留给读者”式的生硬参考手册笔法，关键推理步骤要替读者走一遍。
HN 评论精选
数学写作与其它写作没有本质区别，核心都是把想法传达清楚。
这是 Kevin P. Lee 写的一份实用指南，面向选修数学课的本科生。面向研究论文写作者的类似指南是 Paul Halmos 1970 年的《How to Write Mathematics》。两者的出发点相似：Lee 说，写数学论文的目标是把数学推理和想法清楚地传达给另一个人；数学课的写作和其他课程的写作非常相似，你在心理学、历史、文学课上的许多写作准则同样适用于数学论文。Halmos 说：写数学的基本问题，和写生物学、写小说、写羽管键琴组装说明一样，都是把想法传达出去。
tkgally查看英文原文
This is a sensible guide, by Kevin P. Lee, aimed at undergraduates taking math classes. A similar guide, aimed at people writing research papers, is “How to Write Mathematics” by Paul Halmos (1970) [1]. They both start from a similar assumption: Lee: “When you write a paper in a math class, your goal will be to communicate mathematical reasoning and ideas clearly to another person. The writing done in a math class is very similar to the writing done for other classes. You are probably already used to writing papers in other subjects like psychology, history, and literature. You can follow many of the same guidelines in a mathematics paper as you would in a paper written about these other subjects.” Halmos: “The basic problem in writing mathematics is the same as in writing biology, writing a novel, or writing directions for assembling a harpsichord: the problem is to communicate an idea.” [1] https://www.mathematik.uni-marburg.de/~agricola/material/halmos.pdf
对话式、带读者走完全程的写法，比参考手册式教材有效得多。
我在物理上也有类似体验：直到读了 David Griffiths 的教材（尤其是电磁学和量子力学那两本），这两门课才变得清楚。原因在于他的写法像一次清晰的一对一辅导，用了文中提到的许多“数学写作”做法：口语化，像有人在试着讲解，只是写成了文字。我记得有“现在看看我们得到的这个表达式，它告诉了我们什么？”或者“接下来是一段比较长的推导，但你会发现花力气走完它是值得的”这样的句子。相比之下，大多数教材读起来像生硬的参考手册，动不动就“练习留给读者”。
supernova87a查看英文原文
I don't know if anyone else experienced something similar in physics, but it was not until I read the textbooks of David Griffiths (his books on E&M and quantum especially), that either of these subjects became clear to me. I think the reason is that his writing was like a clear 1-on-1 tutorial session, with many of the "writing mathematics" practices described in the article here. It had a conversational style as if it was someone trying to explain but in written words. I recall phrases like "now look at the expression we have here, what does it tell us?" Or, "what follows is a somewhat long derivation, but you will find the effort of working through it pays off". Most other textbooks read like stilted reference manuals by comparison, with "exercises left to the reader".
推荐 Knuth 的《Mathematical Writing》作为进阶读物。
还有 Knuth 的《Mathematical Writing》可以参考。
cionx查看英文原文
There is also “Mathematical Writing” by Knuth: https://jmlr.csail.mit.edu/reviewing-papers/knuth_mathematical_writing.pdf
过度堆砌记号会妨碍理解，好论文会主动为清晰而做减法。
论文里没有写、但我觉得很恼人的一点是符号负担过重：有些变量带着四五个下标，公式根本没法读。我很欣赏有些论文在某个地方说“为清楚起见，我们省略掉这个或那个与核心思想关系不大的记号”。通常好论文才会这么做。
ptidhomme查看英文原文
What's not in the paper but I find quite annoying in scientific articles is excessively loaded notation. Some variables get to have like 4 or 5 subscripts and equations become unreadable. I really appreciate when papers get to say at some point "for the sake of clarity, let drop this or that notation" that are not that relevant to the key ideas. Usually it's in the good quality papers.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选