什么是一个好的经验法则来做不混淆人们的技术写作

Question

有时候我是个书呆子，甚至连书呆子都不了解我，或者说，有时候我不能用简单易懂的语言来表达我的意思。有时候我只能在事后才能说出来。

我喜欢技术方面的细节，我喜欢写一些关于技术的东西，但有时我不能停下来，也不能判断什么时候太过技术性或太抽象而无法理解。我常常把太多的细节放在一些东西上，认为它会帮助理解某些概念，但有时却适得其反。

这些都是边缘案例，我不太擅长写作(我希望)，但是，什么是好的经验法则，知道什么时候，你可能会让人头晕，当你看你的东西？，你如何测试你的类比？，我正在寻找一个或多个经验法则，以知道我是否写正确的技术解释，知道什么是参考和不参考，等等。

，对于那些不一定熟悉你所写的东西但又不是你所在地区的圈套的技术人员来说，你写技术方面的黄金法则是什么？，线在哪里？

Answer 1

我在技术写作方面的问题一直是，我收集并学到了比技术文档所需要的更多的信息，这些信息产生了一个项目、一段代码。对我起作用的经验法则是，对我所有的信息做一个“大脑倾倒”。然后，在任何事情之前(在构造、语法、拼写、任何事情之前)，我都会编辑文档以删除三分之一的措辞，而不会失去任何意义。(这个数字对我是有用的)。然后，我将开始研究文档的结构和形式--如果必要的话，介绍以前的相关结构示例；或者提供对我试图实现的目标有用的结构的标准文档。

一旦文档被上述过程，以及拼写和语法检查，打成一个粗略的初稿，我就会把文件放在一边至少三天。然后，我会开始修订过程--慢慢地阅读--我已经制作的东西。

外部编辑、评论、阅读或这些内容的某种混合是必不可少的。我发现，特别是技术写作，我完全无法判断自己是否在没有外部输入的情况下“达到了最佳状态”。

Answer 2

假设你的技术写作是为了工作，你总是可以要求同事校对。比想象中你是否过火要容易得多。

Answer 3

没有银弹。这就像问“您如何知道您的软件是否没有bug？”唯一的答案是:事实并非如此。技术写作(以及各种各样的写作)也是如此:你的文字会让一些人感到困惑。判断某人是否被文档弄糊涂的唯一方法是让他阅读。

重要的是，你应该关心人们的阅读方式和他们的背景。给定的文档应该以受众为目标。你应该尽量得到所有你能得到的反馈。有了经验，你应该能够更容易地把自己放在别人的位置上。

最后，编写好的技术文档与编写好的代码一样广泛和复杂。记住，世界上最好的科学家是那些能够在书中或电视上解释事情的人，他们花了20年的时间才发现了一些东西。所以我建议你遵循扬尼斯的建议，在作家上问你的问题，因为它们可能会帮助你问一个更具体的问题。