技术写作与文档2022bhupesh.me
用 Vale 和 Neovim 像专业作家一样写作
Writing like a pro with Vale and Neovim
导读
这篇教程介绍如何把散文检查工具 Vale 接入 Neovim，在写作过程中实时获得文风与用词上的提示。对写作者来说，它的价值不在于「让工具替你写」，而在于把个人或团队的风格规范写成可执行、可复用的规则；评论区的讨论也提醒我们这类工具能查什么、查不了什么。
可以直接用的写作要点
- 01
把自己反复犯的毛病（滥用副词、模糊限定词、句子过长）写成自定义规则，让检查工具替你长期盯住，而不是每次靠自觉。
- 02
Vale 的规则主要基于正则和词性匹配，脱离语境容易误报，例如「write-only」里的 only 会被当成模糊词；工具输出必须人工复核，不可盲从。
- 03
技术写作者可以用这类 linter 保证术语统一、风格一致，这正是长文档和多人协作中最容易失控的地方。
- 04
可读性指标（句长、被动语态比例等）适合当作提醒信号，而不是硬性合格线——真正的判断仍来自你对读者和语境的理解。
HN 评论精选
Vale 的真正威力在于规则可自建、可复用，甚至能拼出一个开源版语法检查器。
评论者指出原文没提到你可以自己写规则，也可以从 GitHub 上挑选现成规则。有人正试着用 Vale 规则做一个开源的 Grammarly：规则大多基于正则表达式，也有一部分针对可读性指标，还有的用词性分析。
adamgordonbell查看英文原文
They don't mention that you can write the rules yourself and also pick and choose from existing rules from GitHub. There is an attempt to build and open source version of Grammarly using vale rules here[1]. Rules are mainly regex based, but some target readability measures[2] or use parts of speech[3]. [1]: https://github.com/testthedocs/Openly [2]: https://github.com/testthedocs/Openly/blob/master/Openly/Readability.yml [3]: https://github.com/errata-ai/vale/issues/356
在技术写作场景中，linter 的实际价值是守住一致性。
作为技术写作者，我每天都在用 Vale，它有助于保持术语和风格的一致性。我还写了一篇入门教程。
remoquete查看英文原文
As a technical writer, I use Vale every day. It helps protect consistency and style. I wrote a brief tutorial here: https://passo.uno/posts/first-steps-with-the-vale-prose-linter/
怀疑论：工具无法替代写作能力本身，别把工程思维套到写作上。
写好文章的办法并不是「给英语做一个静态代码补全或 lint 工具」。这种事只有科技行业才干得出来，典型的「手里只有锤子，看什么都是钉子」。
ComputerGuru查看英文原文
The answer to writing better isn’t a “static code completion/linting tool, but for English.” Leave it to the tech industry to really exemplify the “when all you have is a hammer…” mentality.
误报和解析限制让这类工具在实践中难以真正可用。
我用 good-writing 插件跑了自己的一篇博客，不敢说写得多好，但相当一部分警告是误报——连「write-only」这样的词都会触发针对「only」的模糊词规则。更根本的是技术限制：它用的是 GitHub 风格的 markdown 解析器，会过滤掉 mathp 这类少见的 HTML 标签，我没法让它忽略数学公式部分；改用静态站点生成器的输出又会因为软连字符被它把每个音节当成独立的词。
nagisa查看英文原文
I tried running vale with the good-writing plugin on one of my blog posts. I won’t claim I produce great literary works, but a fair bit of warnings it output were false positives. Even conjugates such as “write-only” would trigger its weasel word trigger for “only”. Ultimately, it is the technical limitations that make the tool unusable for me. On one hand, a Github-flavoured markdown parser is used. It filters out some obscure HTML tags such as `mathp`, and I couldn’t find a way to configure the tool so it would ignore the math segments. I even tried to forgo vale’s built-in markdown converter, and run the check on the output of the static site generator instead, but that plan was quickly foiled by the soft hyphens my generator inserts. Given such an input vale considers every syllable a separate word.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选