技术写作与文档2020qz.com
在工作中编写用户手册能让团队更从容、更高效
Writing a user manual at work makes teams less anxious and more productive
导读
本文介绍一种团队实践：每个人为自己的工作方式写一份"用户手册"，说明自己的沟通偏好、雷区和协作习惯，以此降低团队焦虑、减少摩擦。文章值得写作者一读，因为它示范了"为读者而写"的实用文体：写清自己的使用说明，本质上是在做一次精准的自我描述与预期管理。
可以直接用的写作要点
- 01
写自我说明书时，少写"我重视诚实"这类人人都会说的标签，多写可验证的具体偏好，例如"急事请打电话，别发消息"。
- 02
把"雷区"写成行为和场景，不要写成性格评价，比如"讨论中途打断我会让我卡壳，请让我说完"。
- 03
每条说明都问一句，读的人能凭它做出什么具体动作；做不到就删掉或改写。
- 04
这类文本的最大风险是被断章取义或被权力方利用，因此表述要留有边界，不要暴露可被攻击的私人信息。
HN 评论精选
自我说明可能被权力方选择性解读，直率反而惩罚说真话的人。
这听起来像是灾难的配方。经理说"我欣赏直来直去，想到什么就说什么，别包装"，于是员工一号照字面执行，胡言乱语一通，被当成疯子；员工二号照实执行，说我们的产品在让人生活变糟，被当成不合群。剩下的人要么低头不语，要么借此和经理套近乎。我希望永远不要在那种地方工作。
l0b0查看英文原文
This sounds like a recipe for disaster. Manager: “I appreciate straight, direct communication. Say what you are thinking, and say it without wrapping your message.” Employee 1, taking the advice literally: “I like hats! Do you like hats? Also green, green is good. And chocolate. But everyone likes chocolate, so that doesn't count. Manager: “You’re mad. Security!” Employee 2, taking it honestly but not literally: “Our product is making people’s lives worse. Every study ever made of our business says so. Why don’t we spend all this money doing something worthwhile?” Manager: “Not a team player. Security!” The rest of the employees either keep their heads down or take this as an invitation to get chummy with the manager, offering sage advice from the last tweet they read. I hope I never work at a place like that.
信息不对称会让坦诚者吃亏，须先评估团队是否安全。
这个方法似乎建立在"可以信任所有人"的假设上。一个人分享了自己的性格信息，另一个人不分享，前者就处于劣势。爱操纵人的同事是存在的，自恋型和精神病态的人在公司环境里往往如鱼得水。
b0rsuk查看英文原文
This method seems to rely on the assumption you can trust everyone. If one person shares his personality information and another doesn't, it puts the first person at a disadvantage. Manipulative coworkers are a thing. Narcissistic and psychopatic people thrive in corporate environments.
在健康的团队里，自愿参与的自我说明能显著提升协作。
我们做过，效果非常好。我理解在功能失调的团队或文化有问题的组织里，人们不愿做这件事；而"不敢分享个人信息"在我看来本身就意味着根本性的缺陷。当然，做得对的话没人被强迫。这对团队更有效地协作、减少潜在冲突是很好的体验。
pasta-driven查看英文原文
We did this and it is really great. I can understand that you don’t want to do this in a dysfunctional team or in an organization that has a broken culture (not feeling save to share personal stuff for me implies a fundamental flaw). Of course if done right, nobody is forced to do this. But it is a great experience for the team to get more effective in working together and also reduce possible conflict.
自我描述常流于通用套话，与真实行为相关性很低。
把想法写下来总是很有用的练习，自省是好品质，给自己写一份用户手册是好事。但公司里这些手册是否有用，我存疑：也许你只会得到一条无关紧要的信息，比如某个不常打交道的人说更喜欢邮件而不是聊天。我提个练习：如果手上有别人的 README，遮住名字读一遍，看能不能把内容对上具体的人。我发现毫无相关性——人人都说自己重视诚实，可你依然不知道该怎么和这个人打交道、他真正看重什么。我们其实很不擅长判断自己。
lazyant查看英文原文
Writing down ideas is always a very useful exercise. Having introspection is a good trait, so writing a "User's Manual" for yourself is a very good thing. Now, having these User Manuals in a company, I don't know if they are any useful; you may get the one tidbit of information that somebody you don't interact much with says they prefer email to chat or something. I propose an exercise: if you have people's "README's", go through them, if possible without seeing their names and test if you could match what they say they are/like/etc to who they are and what they actually are like. I simply find no correlation; everybody says they value honesty etc (including myself) and you still have no idea of how to interact with that person, or what they really value. We are really bad at judging ourselves.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选