技术写作与文档2018news.ycombinator.com
写教科书该用什么软件？
Ask HN: What software should I use to write a textbook?
导读
这是一条 Ask HN 提问：写教科书该用什么软件，最终要输出 PDF、未来可能印刷。高赞回答分成两派：一派主张先专注内容、用纯文本或 Markdown 起步，后期再排版；另一派推荐 TeX 系（ConTeXt/LaTeX）或 Pollen 这类能精细控制版式的工具。对写作者的价值在于：它提醒你工具选择应服从“先写完、再打磨”的顺序，也给出了从草稿到成书的可行工作流。
可以直接用的写作要点
- 01
先用最朴素的纯文本或 Markdown 写作，别让排版和视觉效果分散注意力——内容才是重点。
- 02
采用“Markdown 写作 + Pandoc 转换”的流程，便于同一本书生成多种格式、统一多本书的风格、以及日后修订。
- 03
可以把某一章先转成网页发布，试探读者兴趣，再决定是否继续投入整本书。
- 04
若确定要精细控制排版（尤其未来印刷），值得投入时间学 TeX 系；ConTeXt 在版式、多语言、图表和表格上比 LaTeX 更顺手。
HN 评论精选
有余力就学 ConTeXt，排版控制力最强，但要接受其文档门槛。
如果有时间投入，就选 TeX 的一个变体（LaTeX 或 ConTeXt），它能完全控制任何排版细节。我更推荐 ConTeXt 而非 LaTeX：最小文档只需 \starttext … \stoptext，从这里可以走很远，甚至能生成电子书；在版面控制、语言支持、图形集成、表格生成上都比 LaTeX 更好，还与 Lua 深度集成、便于写脚本。它的弱点是文档：内容虽丰富全面，但比较零散、有时过于技术化，不过我认为值得为此付出努力。
lifepillar查看英文原文
If you have time to invest, go for a TeX variant (LaTeX or ConTeXt). That gives full control over any typesetting detail. I’d recommend ConTeXt [0] over LaTeX. A minimal document is as simple as \starttext Start writing here… \stoptext and you can go a long way from there, including making ebooks. Much better than LaTeX for layout control, language support, graphics integration, table generation, etc… It’s also intimately integrated with Lua for your scripting needs. The documentation is possibly its weak point: it’s rich and comprehensive, although somewhat sparse and at times heavily technical. But it’s worth the effort, IMHO. You may get inspired by the TeX showcase [1] (not only ConTeXt, but also LaTeX and plain TeX). [0] http://wiki.contextgarden.net/Main_Page [1] https://www.tug.org/texshowcase/
Markdown + Pandoc：内容与格式分离，复用和试水都方便。
我的流程是先用 Markdown 写（尽量少做样式相关的格式），再用 pandoc 转成想要的格式。这样做出多本外观一致的书、以及后续修订都变得非常容易。一个好处是你可以把某一章转成网页，借此试探这本书本身的受关注程度。
bArray查看英文原文
My process is to use markdown [1] (very little style related formatting) and then convert to a desired format using pandoc [2]. Building multiple books that look the same, later revisions, etc - becomes really easy. One of the benefits is that you can convert a chapter to a webpage and gauge interest in the book itself. [1] https://daringfireball.net/projects/markdown/ [2] http://pandoc.org/
先写完再排版，别在草稿阶段被格式分心。
从纯 ASCII 文本开始。人很容易被格式和外观分心，内容才重要。所以先用记事本、vi、emacs 这类基础编辑器，最多用 Markdown。先把它写完、再编辑，之后才用 LaTeX 或 Word 之类去排版。
segmondy查看英文原文
Begin with plain ASCII text. It's very easy to get distracted by the formatting and looks. Content is what's important. So begin with a basic editor like notepad/vi/emacs. Perhaps at best markdown. Get it done, then edited, then you can typeset with something like Latex/Word.
Pollen 是作者自用出书的成熟方案，成品排版效果出色。
可以看看 Pollen（Racket 语言生态）。作者 Matthew Butterick 用它写了好几本书，比如《Practical Typography》和《Beautiful Racket》，成品效果令人印象深刻。如果我要写书，会从这里开始。它应该能输出 LaTeX，再据此生成最终的 PDF 和 ePub。
aeontech查看英文原文
Check out Pollen: http://docs.racket-lang.org/pollen/ The author of the package, Matthew Butterick, wrote several books with it, such as - Practical Typography: https://practicaltypography.com/ - Beautiful Racket: https://beautifulracket.com/ Looking at the results, I can't help but be impressed. If I was writing a book, I would start here. I think you can get it to output LaTeX which you can then use to generate your final PDF and ePub, if you like. Previous HN discussion here with some other real-world users chiming in with their experiences: https://news.ycombinator.com/item?id=15335010
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选