好的文档可以指导人们更好地解决问题。它很少有趣，但能真正解决了你的问题，这也很重要。
在本指南中，我解释了如何撰写技术类的文档并写得易于理解。这也是我写另一本书的方式。
一致性
你如何使用一个且仅一个术语来描述某个事情。如果可以，请使用最流行的术语（这样大家的接受度会更好些）。
例如，柏林的德语:Ausländerbehörde, 现在是 Landesamt für Einwanderung。但是大家仍然习惯称它为Ausländerbehörde以及在那些德国以外的地区，也仍然被称为 Ausländerbehörde。这就是为什么我总是在我的指南中称它为 Ausländerbehörde。
如果你使用读者不知道的术语，大家的接受度就更重要了。如果您的读者刚刚学会了一个词，他们不知道它的同义词和缩写词。例如，中国方言里面对爸爸的称呼有太多不同的术语，但我总是使用“爸爸”，因为那是通用统一的称呼。
如果同一事物有许多术语，请告诉你的读者，然后始终使用相同的术语。如果使用缩写，那就始终使用它们。不要在一个术语和它的缩写之间交替使用。你可以使用
精确
避免模棱两可的句子。不要让你的读者猜你的意思。你的叙述必须是正确的，并且能被正确理解。如果信息不明确，读者可能会做出错误的决定。
使用正确的情态动词。比如”你可以洗手”，这是可选的。如果”你应该洗手”，这就是建议这样做。如果是“你必须洗手”，这就是必须不容商量的。你可以遵循RFC 2119协议规范（一句玩笑话，搞计算机的就懂这个梗）。
我遵循它，但使用的是“can”而不是“may”，因为“can”是一个更常见的词。
比如举个很好的例子： 冠状病毒疫苗的副作用和安全性- NHS。
当有多选框列表的时候可能会令人困惑。如果你需要使用多选框列表，请告诉你的读者他们是否必须满足一项要求（A或B或C），或所有要求（A和B和C）。
示例、插图和代码片段非常有用。不要只是告诉你的读者如何做某事；让他们看。图片通常是描述结果应该是什么样子的最佳方式（一图顶万言，无图无真相）。
很好的例子：如何更换雷诺 Kangoo 火花塞
最好的例子： 为工程师做饭
有时，计算器给出的答案比长文本更好。借助计算器，你的读者可以快速得到准确的答案。例如，我的健康保险指南在 20 分钟内给出了模糊的指示，而我的健康保险计算器在 20 秒内给出了明确的答案。
简单
去掉每一页上一半的字，然后去掉剩下的一半。 ——史蒂夫·克鲁格，别让我思考
切入正题！请给出最短的完整答案。不要试图变得有趣、聪明。你的目标是解决读者的问题，而不是娱乐他们。
保持简短的介绍。应该确保读者能够找到了正确的页面，仅此而已。有时，你根本不需要介绍。目录就是介绍，有它就够了。
你很少需要结论，但摘要可能很有用。“下一步”部分也很有用。许多指南只涵盖读者旅程中的一步。
不好的例子：每个食谱网站，除了justthefuckingrecipe.net。
使用简单的词汇，写简单的句子。我模仿海明威写得更简单。它帮助我用更简单的单词和句子替换复杂的单词和句子，这样读者就更容易get到你的点。
好/坏的例子： 之前和之后 - 简单的英语运动
不要使用成语的表达方式。如果你的读者不是以英语为母语的人，他们将不会理解棒球的隐喻。你还应该避免开玩笑、讽刺和评论，并专注于提供信息。同样，你的目标是解决读者的问题，而不是娱乐他们。
不好的例子： 如何删除引擎滴答声
结构
您的读者不会阅读全文。他们会跳过句子、段落和章节。这是允许并合理的。你应该帮助他们做到这一点。
将简短答案放在顶部，然后添加更多详细信息。我喜欢将简短的答案以粗体显示在顶部。这种写作风格有时被称为底线在前或倒金字塔。这与点击诱饵相反。
构建你的内容以逐步回答问题。让你的读者决定从哪里开始。目录可以帮助读者选择从哪里开始。
使用标题、项目符号列表、粗体文本和斜体来引导读者找到答案。不要强迫他们阅读对他们来说不重要的东西。
如果可能，在段落的开头加上条件句（“如果你超过 25 岁，……”）。这可以让读者跳过不适合他们的段落。我通常将这些条件语句用粗体表示。
很好的例子： 公共健康保险费用， Finanztip上的大部分内容。
我的大多数指南都有这样的结构:
这个过程是什么 为什么必须这样做 做起来有多难 怎么做 接下来做什么 在哪里寻求帮助
当我编写故障排除指南时，我遵循另一种结构：
问题是什么 有多严重 症状是什么 需要哪些工具来修复它 我是如何解决的 我尝试过但不起作用的事情
你可以通过良好的排版使文本更易于阅读。甚至还可以为提示和警告创建特殊样式。
很好的例子： 为什么我的车过热？
设定期望
读者需要好的信息才能做出正确的决定。告诉他们在哪里，要去哪里，需要多长时间，花费多少，以及预期的结果。这可以为他们减轻很多心里负担（俗称傻瓜式引导）。
如果可以，请使用精确的数字。例如，责任保险在德国非常重要：82% 的德国人拥有它。德国工作签证通常在 8 到 12 周内获得批准。我的龙须面需要30 分钟才能准备好。
当您不能使用数字时，请使用“很少”、“有时”、“通常”、“大部分时间”和“总是”等词。你还可以告诉读者某事有多难，从“非常容易”到“几乎不可能”。使用一致的词汇来表示频率、可能性和难度。
如果可能的话，告诉你的读者哪里出了问题。在他们发生之前警告他们可怕和压力的部分。
有时，您需要告诉读者错误的答案和无效的解决方案。例如，一篇关于宿醉治疗的文章应该提到无效的常见治疗方法。
很好的例子：
结肠造口术：期待什么 所有关于时期 准备第一次酸性旅行 在您的 Ausländerbehörde 预约期间会发生什么
修订
好的文档是一步一步迭代产生的。你将多次重写你的内容，即使在发布之后也是如此。我已经更新了一些指南数百次。我已经数次完全重写其中部分内容。
写清楚是一种技能。你会通过练习变得更好。随着时间的推移，你会找到更好的方法来说明事情，以便更清晰。
作为专家，可以忘记成为初学者的感觉。这是专长的诅咒。通过倾听读者的心声，找出让他们感到压力和困惑的地方，你可以学到很多东西。他们的问题是你将获得的最佳反馈。
随着时间的推移，你将了解你的领域和您的读者。例如，我对德国移民了解很多，但对在德国学习或抚养孩子几乎一无所知。我从我的读者那里了解到。我还学到了很多关于租赁市场、移民法、保险和许多其他主题的知识。
————————-全文完——————————————————
如果你觉得受益欢迎赏杯咖啡，赞助点能量！感谢！
