技术写作与文档2020boringstartupstuff.com编辑精选
你应该写一份用户指南
You Should Write a User Guide
导读
这篇讨论“个人用户指南”（User Guide / Personal User Manual）：把自己喜欢的工作方式、沟通偏好写下来给同事看。对写作者的启发在于如何用清晰的书面文档表达自我设定与边界，以及写下来的原则如何真正改变他人的行为。
可以直接用的写作要点
- 01
把抽象偏好写成具体可执行的原则（如“周末不回邮件”），比笼统描述更有效。
- 02
文档要配上一致的行动：只有严格执行，别人才会真正按你写的方式与你协作。
- 03
如果“个人用户指南”显得自我中心，可以换个中性标题如“工作原则”，内容不变。
- 04
写作前先权衡利弊并参考模板，团队集体撰写并汇总效果更好。
HN 评论精选
现实中同事往往不读你写的文档，单靠文档难以改变他人的沟通方式。
我作为开发者的经验是：同事不在乎我的状态（忙碌、勿扰），不在乎我的沟通偏好——只要他们没被卡住就会打电话，也不认可任何不是他们自己做的优先级排序。最相关的是：他们根本不读我写的关于我自己或软件的文档，连邮件内容都很少看。我在中型分销公司工作，至今没找到办法让同事理解专注时段和明确沟通渠道有多重要。在我看来，再写一份文档也不会有用……
the_cramer查看英文原文
My experience as a developer is - people don't care about my status (e.g. "busy", "dnd") - people don't care about my communication preferences -- if i'm not blocked they will call, no matter the priority - they are not interested in any priortization not done by them. And last and the most related to this approach: - They do not read any documentation I write about me or my software. They hardly read the contents of mails. I shoud remark that i do not work for a software-house but in medium scale distribution. Still did not find a way to communicate to my peers on how important phases of concentration and defined communication channels are. In my opinion, another documentation is not gonna work... edit: formatting
与其让人读指南，不如用一致的行为示范来建立你的工作原则。
如果让同事看“某某用户指南”让你觉得别扭，可以改叫“工作原则”并保持内部使用。然后严格、一致地执行这些原则，别人会注意到并相应调整与你的互动方式。比如我周末基本不回邮件，只需一两个周末，别人就明白了。再比如重要请求发到 Slack 或短信上时，我会请对方改发邮件，几次之后大家就摸清规律了。我认为这比让人去读用户指南更友好。
gk1查看英文原文
If pointing colleagues to a "Gk1 User Guide" feels self-centered or weird for any reason, call it "Operating Principles" and keep it internal. Then adhere to these principles strictly and consistently. Others will notice and change the way they interact with you accordingly. For example, with a few exceptions, I don't answer emails on weekends. It only takes one or two weekends for someone to realize this, and either stop emailing me on weekends or learn to not expect an answer until Monday. As another example, if an important request, decision, or question is sent to me on Slack or text, I kindly ask them to send it to me by email. A few instances of this and people figure it out. This is, I think, a much more friendly way of changing people's behavior than pointing them to a user guide.
写下个人偏好（如何接受表扬与批评）是帮助经理管理你的有效工具。
每次这个话题出现我都持不同意见：我认为把一般性原则写下来给团队尤其是经理看是好事——我喜欢怎样的表扬？喜欢怎样的批评？什么让我感到被重视？经理的职责就是让你保持快乐和高效，了解这些是他们的本职。如果经理或同事因此嘲笑你，那说明这个环境不重视团队合作和彼此关心，我会选择离开。
madamelic查看英文原文
Every time this is posted, I go against the grain and agree with something like this. I think having general principles written down and available for your team or especially your manager is good. - How do I like praise? - How do I like criticism? - What makes me feel appreciated? etc. Your manager's job should be to keep you happy and productive. Knowing what makes you productive and happy at a company is their job. Maybe I am just a weirdo Millenial who hates corporate places but if my manager or colleagues laughed at this or anything in that sort, I would leave since that signals a poor environment that is not about teamwork and being caring of others.
团队集体撰写个人用户手册并汇总共享，在远程办公时期尤其有用。
我犹豫了很久要不要写，最后写了一篇，团队反响很好。后来大多数成员都写了自己的，我们汇总放在文档空间里。这在封锁的头几个月特别有用，因为那时大家的工作偏好和限制差异很大。我还写了一篇关于个人用户手册利弊和建议的文章。
caminmccluskey查看英文原文
I went back and forth on whether it was a good idea. In the end I wrote one and it was well received by my team. Indeed, most of the team wrote one and we collated them in our documentation space. This was pretty helpful in the first few months of lockdown, when people's work preferences and constraints were quite varied. I also decided to write up a short piece on the pros and cons + some advice if you are considering writing a User Guide (or README or Personal User Manual) - https://medium.com/better-programming/personal-user-manuals-the-good-the-bad-and-the-template-7b80db5044ea [Edit: Grammar]
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选