技术写作与文档2020paperplanes.de
如何起草工程战略
On Drafting an Engineering Strategy
导读
这篇文章讲的是工程领导者如何起草一份技术战略文档：不能凭空写下抽象目标，而要让它扎根于业务语境和系统现实。两条高赞评论从被管理者的视角补充了反例——脱离语境的目标会变成无人理会的"象牙塔"，堆砌时髦术语的"战略"则是强加给团队的空话。写战略、规划、提案类文档的人都能从中照见自己常犯的毛病。
可以直接用的写作要点
- 01
写战略或规划文档时，先交代业务语境和"为什么要做"，否则读者只会把它当成空降的戒律。
- 02
不要写凭空冒出的抽象目标句；要让每条目标都能让一线团队立刻看到它与自己工作的关系。
- 03
警惕借用会议上听来的时髦术语，只用自己真正理解、能说清代价的词。
- 04
用一线视角检验文档：如果资深工程师只能用"说来话长"来解释它的存在，那这篇就失败了。
HN 评论精选
战略若不讲清业务语境，就会变成无人理会的象牙塔。
这是一篇相当不错的文章，作者看起来是个有想法的人。希望更多技术领导者读到它，哪怕不完全认同，也能理解其中提倡的理念。我太常遇到这种情况：新领导一上任就立刻抛出一堆戒律，却几乎不交代与业务的关系。象牙塔在手下人的帮忙下建了起来——有人不情愿地被指派，有人心甘情愿地买了宏大计划的账。因为看不到项目的直接业务价值，大多数团队要么躲着它，要么只做最低限度的工作来应付。每次都是如此：大约一年后，象牙塔还立着，但人已经散去，成了没人愿意再想起的遥远遗迹。领导调去了下一个岗位，新工程师问资深工程师这座塔为什么存在，他们笑笑说："请我喝杯啤酒，说来话长。"
pm90查看英文原文
This is s pretty great article by a seemingly thoughtful individual. I hope more technology leaders read it and understand if not embrace the ideas it promotes. Too often, I've been in the situation where a new leader will step into a role and immediately start throwing out commandments with little context as it relates to the business. An Ivory tower is built with the help of minions, assigned unwillingly or willingly bought in to the Grand Plan. Not seeing the immediate business value of the project, most teams avoid it or do the minimum work necessary to satisfy the requirements. Literally every time this happens, after about a year the Ivory tower remains up but is depopulated, a forgotten relic of a distant past that nobody really wants to think about. The leaders move on to the next role, and when new engineers ask senior engineers why the Ivory tower exists they smile and say: "buy me a beer; t'is a long tale"
战略语言若只是堆砌时髦术语、脱离真实约束，就成了强加给团队的空话。
天啊，这家伙怎么没意识到自己已经变成了《狗屁工作》里那种没用的总监？你在这里看到的正是大公司里那些蠢事的起点：凭空冒出、毫无来由的"目标"句子。比如这句："将核心功能模块（包括认证、用户数据、购物车）迁移到独立于主应用运行的微服务架构"。在我看来，这就是那种被强加给团队的、空泛的技术决策。我们都经历过：某个对真实技术栈和系统约束一无所知的无用总监，想让自己显得有用，于是定义一个"狗屁"战略，把他最近在会议上听来的时髦玩意强加下去，却并不真懂那意味着什么。
greatgib查看英文原文
Omg, how can this guy not notice that he became an useless director as in 'bullshit jobs'? Here you see the inception of the stupid things you see in big companies: like determining useless 'objectives' sentences coming from nowhere. Look at this for example: "Migrate core functionality pieces (including authentication, user data, shopping cart) to a micro services architecture that’s running independently of our main application" To me it looks like the kind of stupid generic tehnical decisions that are imposed on teams. We have all lived that: some useless director that has no idea of the real technical stack or constraints of the system wants to feel useful and define a 'bullshit' strategy, so what it does is imposing the last trendy thing he heard at a conference without really knowing what it means.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选