技术写作与文档2018github.com
SugarTeX：更易读的 LaTeX 扩展与转译器
Show HN: SugarTeX – readable LaTeX language extension and transcompiler to LaTeX
导读
这是 SugarTeX 的作者在 HN 上介绍的一个 LaTeX 扩展与转换器：它用 Unicode 让公式源码更接近可读的纯文本，方便嵌进 Markdown。虽然话题偏技术，但对写作者仍有启发——它讨论的正是“源码也要像人话”的可读性原则，评论里关于示例、动机和与既有标准对比的批评，也适用于任何技术文档或说明性写作。
可以直接用的写作要点
- 01
把最有说服力的示例（输入与输出对照）放在开头最显眼处，不要让读者自己去仓库深处翻找。
- 02
开头就写清“为什么要做这个、解决什么痛点”，而不是让读者从细节里猜你的动机。
- 03
提出新方案时主动与已有的类似标准（如 UnicodeMath）对比，说明差异与取舍。
- 04
把可读性当作设计目标而非副产品：如果你的格式编译前就像天书，读者很难信任它。
HN 评论精选
示例和对比是说服读者的第一要件，缺了就没人看得懂价值。
这个项目急需把公式的示例（源码和渲染结果）放在最显眼的位置。没有这些，很难理解它到底有什么用。另外如果能和 UnicodeMath 做个对比也有帮助——后者看起来非常相似，而且是已经在 LaTeX 里可用的现有标准。
mkl查看英文原文
Hi, this desperately needs examples of formulas (code and rendered) front and center. It's pretty hard to understand how this could be useful without that. A comparison to UnicodeMath (which seems very similar and is an existing standard which already works in Latex) would also be useful.
先讲清核心设计哲学，并回答读者最自然的“实际怎么用”疑问。
我猜你的意图是：用 Markdown 那套“不编译也能当纯文本读”的哲学，把 LaTeX 融进 .md 里，对吗？如果是这样，这句话应该放在最上面，现在实在很难看出来。这个想法说得通，但我不确定它是否更好。你指望人们直接输入“ ⃗E”和“⨌”这样的字符吗？还是先打 TeX 再由 Atom 自动补全成 Unicode 符号？
ajkjk查看英文原文
As far as I can deduce, you're trying to incorporate LateX into .md using the Markdown Philosophy of "you should write something that's readable as plain text, without compilation, also". Is that basically right? If so it should probably be right at the top, because it's hard to tell right now. The idea makes sense, though I'm not sure if it's... better. Do you expect people to input " ⃗E" and "⨌" as text? Or ... what? Do you type the TeX and then have Atom autocomplete it into the Unicode symbols?
对“再加一层抽象”的必要性提出质疑：先证明原有方案确实不够用。
标准 LaTeX 在它原本的用途上已经好好地工作了三十五年：写学术论文，让数学公式、图表和引用更漂亮，以及书籍这类重型排版。不太明白为什么大家非要在这上面再叠一层——在我看来这是没必要的过度抽象，LaTeX 并没有那么难读。
kingkongjaffa查看英文原文
Standard LaTeX has worked just fine for like 35 years for the use cases it was intended: academic papers to write better looking mathematics and figures/citations, and heavyweight typesetting of things like books. Not really sure why people are insistent on building on top of stuff - it's taking abstraction to a new level that imho is not needed - LaTex isn't particularly unreadable.
作者自述：以“源码可读”为目标，用 Unicode 降低 LaTeX 的阅读门槛。
SugarTeX 是一个更易读的 LaTeX 语言扩展和到 LaTeX 的转译器，设计用来替代在 Markdown 里插入 $formula$ 的写法。我用 Markdown 加 Python 代码块、通过 Pandoctools 做文档编程（类似 R-Markdown）。Python 和 Markdown 都是可读性很好的语言，可惜 LaTeX 不是。所以我写了这个高度可读的扩展加转译器，为此大量使用 Unicode，安装说明里甚至给出了推荐的等宽字体回退链。输入到输出的转换示例在文档 PDF 末尾。
kiwi0fruit查看英文原文
SugarTeX is a more readable LaTeX language extension and transcompiler to LaTeX. Designed to be used instead of $formula$ insertions to Markdown. I use Markdown with Python code blocks for document programming via [Pandoctools](https://github.com/kiwi0fruit/pandoctools) (like R-Markdown). Both Python and Markdown are very readable languages. Unfortunately LaTeX is not like this. So I wrote SugaTeX extension+transpiler that is highly readable. In order to achieve this it heavily uses Unicode so that SugarTeX install instructions even have recommended monospace font fallback chains. [SugarTeX repo](https://github.com/kiwi0fruit/sugartex) with description. Example of input to output conversion is at the end of [this PDF](https://github.com/kiwi0fruit/sugartex/blob/master/sugartex.pdf?raw=true).
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选