技术写作与文档2018blog.pragmaticengineer.com编辑精选
通过写下来并分享来扩展工程团队——即 RFC 文化
Scaling Engineering Teams via Writing Things Down and Sharing – Aka RFCs
导读
这篇文章讲工程团队如何通过把决策写下来、公开征求评论（RFC）来扩展规模：文档让技术讨论围绕方案本身展开，减少政治博弈，也方便新人上手。对写作者而言，它提供了一个可复用的写作场景——用结构化文档推动协作、评审和决策。
可以直接用的写作要点
- 01
重要提案先写成文档，明确问题、方案和取舍，让讨论围绕内容而不是会议话语权展开。
- 02
用模板把常见评审问题前置回答，能大幅降低别人审阅和作者返工的时间。
- 03
文档的价值取决于问题清晰度：问题清楚时写设计文档，问题不清楚时先用短周期探索再成文。
- 04
推动文档文化不能只靠倡议，要有制度约束和同侪示范，否则容易被赶工和政治因素压过。
HN 评论精选
RFC 难落地，阻力来自组织文化、承包商激励和决策者技术深度不足。
这种事听起来简单，却很少真正做到，而且有很多文化力量在阻碍它。它能解决重要技术决策中的一个问题：如何权衡工程价值，把精力放在技术优劣上，而不是政治上的认可。我在一个规模不小的政府机构工作，领导几乎全是非技术背景（这说得通，因为我们不是以技术为使命的组织），技术管理几乎都是项目管理、业务分析、战略；具体建设几乎全是承包商。这意味着要做技术决策很难评估，因为技术经理不知道 MySQL 还是 Postgres 更好，而承包商有动机不邀请其他承包商评审，只把东西做到“合同验收够用”。于是如果开发者选了 MySQL，项目经理因为预计能按时交付而满意，就有两股大力量都不愿评论设计。我们刚开始尝试 RFC 流程，但额外评审成本很挑战。表面上看，是因为在开工前让一大群人看你的设计会带来组织风险；更深层看，这要求决策者有更高的技术深度。
prepend查看英文原文
This one of those things that sounds simple to do, but is rarely done. And there’s lots of cultural forces that work against it. I think it addresses a big problem with important tech decisions- how to weigh engineering value and focus energy on the technical merits, not on political buy-in. I work within a decent size government org where leadership is almost exclusively non-tech (makes sense because we’re not an org with a tech mission), and almost all tech management is program mgmt, business analysis, strategy. And the building is almost exclusively contractors. This means to make a technical decision, it’s hard to evaluate because the tech manager doesn’t known whether MySQL or Postgres is better, and contractors have incentives to not invite review by other contractors and making it “good enough” for contract acceptance. This means if a developer picks mysql, and the project manager is happy because it’s projected to be delivered in time, then there’s two big forces that don’t want comment on design. We just started to try a request for comment process, but the extra effort to review is challenging. I think that on the surface it’s because letting large groups see your design before start introduces organizational risk. And then a bit deeper is that it requires a greater level of technical depth in decision makers.
文档是团队扩展的首要瓶颈，设计文档的适用场景要匹配问题清晰度。
这听起来就是在描述设计文档（Design Document）；当问题空间理解得比较清楚时，设计文档非常有价值。对很小的团队或与承包商合作时，它可以替代冲刺和冲刺计划。当问题理解得不够清楚，比如不能只靠前期工程规划解决、需要用户输入时，我喜欢 Google 的设计冲刺（Design Sprints），用一周流程找出关键功能。以我领导工程团队和创办、发展初创公司的经验，我完全同意：在其他条件相同的情况下，文档是扩展工程团队的头号阻碍。如果设计、规划和执行过程都有良好文档，工程师一入职就能上手，而不会太拖慢团队。
doublerebel查看英文原文
This sounds like a description of a Design Document, which are very valuable when the problem space is well understood. It can serve as an alternative to sprints and sprint planning for a very small team, or when working with contractors. When a problem is not as well understood, e.g. can't be solved just by engineering planning upfront and needs user input, I like Google's Design Sprints which uncover the critical features using a 1 week process. With my experience leading engineering teams and growing startups, I agree completely that documentation is the #1 blocker in scaling engineering teams, all else being equal. If the design, planning, and execution process are well-documented then engineers can be onboarded as soon as they are hired without slowing down the team too much.
强制文档加模板能减少评审往返、节省时间，并靠同侪压力维持。
我工作过的最成功的公司（90 年代末，创始人在 IPO 后当了几个月亿万富翁，99.9% 的 HN 读者每天都在用我们所做东西的演化版）有一条政策：任何技术功能或重大改进提案，除非妥善记录，否则一律拒绝。我们有一组模板，覆盖常用文档类型。我可以在一个或两个小时内写出一份功能提案，模板确保第一轮问题都在文档里预先回答，节省了大量员工时间。技术创始人设立这套东西并强制所有人使用；一旦我们看到价值，同侪压力就让它在组织中延续。它运作得非常好。我们写的不是 RFC，但我们有一套尊重、也节省每个人时间和注意力的文档流程，这帮助我们作为一个团队快速前进。它真的有效。
faster查看英文原文
The most successful company I ever worked for (late 90's, the founder was a billionaire for a few months after the IPO, 99.9% of HN readers use an evolution of what we built every day) had a policy of rejecting any proposal for a tech feature or significant improvement unless it was properly documented. We had a collection of templates for the types of documents we used. I could create a feature proposal in an hour or two, and the template ensured that all first-round questions were answered out of the box, saving many hours of staff time. The tech founders set this up and forced everyone else to use it and once we saw the value, peer pressure kept it going. It worked incredibly well. We weren't writing RFCs, but we had a doc process that respected (and saved) everyone's time and attention. That helped us move fast together. It really worked.
现实常被赶工和政治主导，RFC 文化需要对抗激励和权力。
抱歉，我要在这里愤世嫉俗一下。作者知道现在有多少人真的在意澄清和规划事情吗？更别说写文档了。零。我在许多从小到巨大、以及中间规模的公司工作过，通常过程恰恰相反。心胸狭窄的管理者和缺乏安全感的工程师想尽快把东西建出来，觉得这是他们留下历史印记的大好机会。于是他们以光速实现一堆垃圾（甚至经常看到不同团队同时在做同一个东西！！！）。六个月后，他们每周都在补 bug！如果你提到让他们慢下来、先找个可用例子再动手，或者至少通过探索问题域来组织工作，他们就会把你霸凌到消失……典型案例：Facebook 的“快速行动，打破常规”。我学到的一点是，在 21 世纪的 IT 工程公司里要成功，就是让白痴用他们的白痴方式去做，自己专注自己的工作；如果他们提出愚蠢的东西，就随它去。政治永远比工程考量更强。也许 Uber 一开始做对了，我无法确认这个说法。但我非常怀疑任何成熟组织会朝作者提议的方向改变。
fogetti查看英文原文
I am sorry but I will be cynical here. Does the author know how many shit people give about clarifying and planning things these days? Let alone documenting. ZERO. I worked in many companies scaling from small to huge and in-between and generally the process is the exact opposite. Small minded managers and insecure engineers want to build things as fast as possible thinking this will be their big chance to leave a mark in history. So they implement some crap (not uncommon to even see different teams building the same thing at the same time!!!) with the speed of light. Then 6 months later they keep patching bugs every week! If you ever mention them to slow down or try to find a working example before building or at least organize the work let's say by starting to explore the problem domain they would just bully you into oblivion... Case in point: Facebook. 'Move Fast and Break Things' One thing I learned is that being successful in an IT engineering company in the 21st century is let the idiots do their idiotic ways and concentrate on my work and if they propose stupid things than let be it. Politics are always stronger then engineering considerations. Maybe Uber got it right from the beginning, I cannot confirm that claim. But I am very skeptical that any established organization would change in this direction proposed by the author.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选