技术写作与文档2022twitter.com
给公式加注释，让论文更易读易懂
Annotated equations for increased readability and understanding of papers
导读
这条帖子展示了给论文里的公式加标注（箭头、说明、颜色、符号高亮）的做法：作者主张这样能显著降低陌生领域读者的理解成本。对写作者而言，这是一个通用提醒：读者看不懂你的公式，并不一定是他们不够聪明，往往是你没有给新符号留出足够的解释接口。
可以直接用的写作要点
- 01
给公式里的新符号配上就地注释（箭头、旁注或颜色），让读者不必来回翻找定义。
- 02
同类项用同一种颜色，或同一类符号用同一套视觉标记，帮助读者用眼睛而不是记忆来跟踪推导。
- 03
把注释做成可开关的一层：内行读者可以关闭它，获得干净的公式；外行读者打开它，获得解释。
- 04
在条件允许时，让符号能链接回它第一次被定义的地方，这对需要复现计算过程的读者尤其有用。
HN 评论精选
标注对跨领域读者价值最大，做成可开关就能兼顾内行与外行。
熟悉某领域数学符号的人往往希望保持紧凑、纯黑墨水的公式原貌；但作为一名偶尔要把陌生数学领域的论文翻译成代码的工程师，这类标注能极大提高我在有限时间内从论文中获得的价值。作者也提到，数学语法高亮对吸收新数学很有用。那么，如果把这种标注做成在线版本里可开关的，是否两类读者都能接受？
nitrogen查看英文原文
From comments here it sounds like people already deeply familiar with the mathematical notation used in a domain really want to stick with the compact, black-ink-only equation representation. However, as an engineer who occasionally wants to translate papers from a mathematical field I rarely encounter into code I will use all the time, annotations like this would greatly increase the utility I could derive from a paper in a given amount of time. Also, as yunruse mentioned in [0], and as I have done in my own videos that include math, syntax highlighting for math is very useful for absorbing new math. How acceptable would that be to practitioners already deep in their fields? So, could annotations of this form be acceptable to both groups if they were switchable on or off in an online version of a paper? [0] https://news.ycombinator.com/item?id=29899938
让符号可追溯回定义处，是减少读者复现成本的关键。
读工程类论文时，我很希望能点击公式里的符号，直接跳回该术语第一次被定义的地方（可能是另一个公式，也可能是正文）。在复现计算时，这种回溯是巨大的痛点，期刊或 LaTeX 应该能自动化实现。
orforforof查看英文原文
For many of the papers I read (engineering) I would love to be able to click on symbols in an equation and have it link me back to where that term was first defined in the paper, either in another eqn or in the text. Tracing back in this way is a major pain point e.g. when trying to reproduce calculations. Seems like something journals/latex could easily implement in an automated fashion (maybe already possible?)
颜色是最低成本的视觉注释：同类项同色，读者一眼就能看出结构。
我一直很喜欢公式里的语义着色。3Blue1Brown 等数学类 YouTuber 常把同类项涂成同一种颜色，提供类似美化排版的细微视觉辅助。
yunruse查看英文原文
Tangentially, one of the things I always enjoyed seeing in the wild was semantic colouring in equations. The educational YouTuber 3Blue1Brown [0] and to some extent the maths side of YouTube in general tend to make use of them, colouring like terms the same to give a subtle visual aid, similar to pretty printing. [0] https://youtube.com/3blue1brown
注释若维护成本过高，作者就不会用；应把它做成可复用的模板或工具。
这种做法有价值，但目前用起来太麻烦：需要大量重复代码，还得手动设置箭头和注释的位置与长度，反而违背了让作者专注内容的初衷。把它封装成一个工具包会很有意义。
mbokinala查看英文原文
I definitely see value in this, but it's currently too much of a hassle to use. It requires lots of tedious code duplication and requires the user to manually set positions and lengths for the arrows and annotations, defeating the purpose of allowing writers to focus solely on the content of their work. However, this would be a great thing to try to encapsulate in a package.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选