写作方法2022matt.blwt.io编辑精选
培育写作文化的工具（2021）
Tools for a Culture of Writing (2021)
导读
这是 Matt 关于如何在团队中建立"写作文化"的工具箱式文章：把写文档当作思考与决策的一部分，而不是事后补的负担。评论区的共识很有意思——写并不难，难的是有人读、文档不过时、以及多年后还能找到。对任何需要写技术文档、决策记录或团队写作的人都有参考价值。
可以直接用的写作要点
- 01
把写作前置：先写文档再写代码，用写作来梳理设计思路，而不是等做完再补。
- 02
为"决策记录"设一条门槛，比如影响范围超出当前任务、日后可能被追问"为什么这么做"时就值得写。
- 03
降低写作入口：一个 README.md 就能开始，不必一上来就搭复杂工具链。
- 04
写完不等于结束，要为文档设计可检索的结构和归档方式，否则两年后没人找得到。
HN 评论精选
决策记录的最大难题是识别"这原来是个决策"，需要一条可操作的触发标准。
我纠结的一点是：什么时候该写决策记录？很多决策是在我们没意识到它是决策的情况下做出的——有时只是回复一条评论、会上随口一句，然后落到代码里就成了决策，通常只留在 commit message 的"为什么"里。判断标准是什么？多大的决策才值得写一份 DR？触发"我必须为此写 DR"的信号是什么？
rchaves查看英文原文
One point I struggle with is when to write a decision record. There are many decisions that go through without us even realizing it was a decision, sometimes it was just a reply to a comment, or something said on a meeting, which you put on the code and boom, a decision, usually logged only on the “why” of a commit message What would be the rule of thumb, which decision size is big enough to worth a DR, what triggers “I have to write a DR for this”?
写作的成本低，阅读与维护的成本高；文档的"定稿感"反而是陷阱。
写其实很容易，读才是难点。要读的东西多到离谱，加上维持信息最新非常困难，这让阅读变得更糟——"这份文档可能已过时，我是该硬读，还是直接去问那个脑子里有全部信息的人？"书面作品被赋予了一种被夸大的"定稿感"。它们适合记录决策背后的部分推理，但即便是这部分也相当零散不全。
gilbetron查看英文原文
Writing is pretty easy, reading is the hard part. Between the ridiculous amount needed to read, plus the fact that maintaining up-to-date information is really difficult and how that makes reading even worse ("Should I bother reading this when it is out of date, or just talk to the person that has it all in their head?"). Written works have an over-exaggerated finality to them. They can be good for capturing some of the reasoning behind a decision, but even then, it is only somewhat spotty.
工具不是瓶颈，缺乏阅读与写作的文化才是。
我经手的每样东西都写大量文档。同事们既不读，也不试着从我的做法里学。但我走到哪儿都继续写，因为我就是靠先写文档、或文档与代码并行来设计应用的，写作帮我思考。我不认为工具是问题所在。试过 Sphinx 和 Notion 之后我主要用 README.md，入门门槛极低。可他们不在乎，坚持用一次性 hack 解决问题，连根因分析都不写。正如其他人所说，我们需要的是培养阅读和写作文档的文化。我们的 CTO 说想建这种文化，但中间显然断了一环。
stonecharioteer查看英文原文
I write copious documentation for everything I touch. My colleagues do not bother to read them, nor do they try to learn from my practices. I continue to do so, everywhere I go, because I design my applications by writing documentation first, or alongside my code. It helps me think. I do not think that tools are necessarily the problem. I use README.md files mostly after trying to use Sphinx and Notion. This has a very low entry point. But they do not care. They insist on using one time hacks and never documenting things, even Root Cause Analyses. Like others have said here, we need ways to improve and build a culture of reading and writing documentation. Our CTO says he wants to build this, but there's some disconnect.
真正的难点是文档的组织与检索，而非单篇写作。
这个前提就错了。难的不是文档的结构和目的——你可以随手定个临时结构，只要力求清楚就行。难的是"图书馆"：你怎么组织这些记录，让两年后的人还能用得上。
coffeefirst查看英文原文
The premise is wrong. The hard part isn’t the structure or purpose of the documents, you can do an ad hoc structure and just strive to be clear. The hard part is the library. How do you organize all these records so they might be usable by someone two years later.
同类还值得读
被低估的工程技能：把文章写好
Undervalued Engineering Skills: Writing Well
这篇文章讨论为什么“写得好”是被低估的工程能力，以及它如何在团队协作、系统设计和职业发展中持续带来回报。
写作方法2019 · 1,109 分 · 371 评4 条写作要点编辑精选每行只写一句话：让写作和修改都更轻松的排版法
Writing one sentence per line
这是 Derek Sivers 的一篇短文，主张写作时每行只放一个句子，而不是按段落排版。
写作方法2022 · 849 分 · 297 评4 条写作要点编辑精选书面沟通是远程工作的超级能力
Written communication is remote work super power
这篇文章讨论远程工作中书面沟通的价值，评论区则补充了异步与同步沟通的适用场景，并提醒读者：备忘录、结论先行、结构化命令格式等书面沟通传统早已有之。
写作方法2020 · 831 分 · 190 评4 条写作要点编辑精选如何写出有用的文字
How to Write Usefully
保罗·格雷厄姆在这篇文章里给"有用的写作"下了一个可操作的公式：有用≈重要×新颖×正确×清楚，任一项为零，整篇文章就等于零；他还主张敢下确定判断、删掉让自己心虚的句子。
写作方法2020 · 821 分 · 285 评4 条写作要点编辑精选如何写得更清楚、想得更清楚，并学会复杂材料（PDF）
How to write more clearly, think more clearly, and learn complex material [pdf]
这份 PDF 讨论如何把文章写清楚、把思路理清楚，并用写作来学习复杂材料。
写作方法2022 · 779 分 · 153 评4 条写作要点编辑精选