技术写作与文档2017medium.com
用故事讲解微服务架构：第二部分
An Introduction to Microservice Based Architecture Through Story – Part 2
导读
这篇文章用故事形式介绍微服务架构，属于系列第二部分。对写作者来说，它值得读的地方在于：技术叙事不能只把复杂问题讲成顺利童话，还要在细节、节奏和选型理由之间取得平衡。
可以直接用的写作要点
- 01
故事化技术写作要在“有血有肉”的细节和“可一口气读完”的篇幅之间找平衡。
- 02
不要只写顺利结局，要呈现真实摩擦、代价和约束，否则容易显得肤浅。
- 03
关键技术选型要交代理由：为什么选它、团队和成本条件是什么。
- 04
用故事说明复杂方案何时该用、何时不该用，而不是默认推荐。
HN 评论精选
故事化技术写作要平衡细节与篇幅，避免把复杂过程写成顺利童话。
一点反馈——我喜欢这个思路，但觉得它太简短，因此显得有点肤浅……它似乎暗示除了路上有些小磕碰，一切就神奇地幸福美满了。用故事讲法难就难在找到那个甜点：细节足够让故事有肉，但又不过度详细到要花两小时全神贯注去读。（我也不知道怎么找到这个甜点，所以不是扔石头。只是想给点反馈，或许有帮助。）
charlieflowers查看英文原文
A little feedback -- I like the idea, but I think it is too brief, and therefore comes across a bit superficial ... it seems to imply that everything was magically happy ever after other than a few bumps in the road. The struggle with the story-based approach, I guess, is to find the sweet spot where you're detailed enough that the story has some meat to it, but not too overly detailed such that it takes 2 hours and deep concentration to read. (I don't know how to find that sweet spot, so I'm not throwing stones. Just wanted to pass on some feedback in case it helps).
技术叙事中关键选型需给出理由和约束，否则显得随意甚至浪费。
挑刺：从架构角度看，我不明白为什么要选择“在 Amazon 之上自建云”，而不是利用 Amazon 的技术栈，尤其作者指出这是个小团队。也许是资源问题，或者他们需要一些在 Amazon 上太贵的东西，但作者至少应该说明为什么选 Kubernetes。抱歉 rant，但我见过太多这种做法，浪费公司宝贵的钱。
ToJans查看英文原文
Nitpicking: from an architectural point of view, I don't see why you would opt for "build you own cloud on top of Amazon", as opposed to leveraging the Amazon stack, especially because the author points out it is a small team. Maybe it's a resource issue, or they need some things that cost too much money on Amazon, but the author should at least justify why kubernetes was chosen. My apologies for ranting about this, but I've seen this approach way to much, wasting valuable company dollars.
用故事应揭示采用微服务的条件与复杂度，而非默认推荐。
它表明微服务会带来很多复杂性。只有当团队变大、用大团队构建应用出现问题时才该这么做。拆分团队，拆分服务。让团队部署各自的服务。
TeeWEE查看英文原文
It shows that microservices come with a lot of complexity. Only do it when your team is growing bigger and there are problems in building your app with a big team. split up the teams, and split up the services. Let teams deploy the services.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选