如何撰写技术帖子，这样人们就会阅读它们(2019年)

当今函数式编程领域最好的博客作者之一是Chris Penner。尽管如此，克里斯还是被刑事低估了--与我交谈过的人似乎都不知道他的作品。你一看完这篇帖子就去看看他！

这在我们的亚文化中相当普遍；有很多奇妙的作品正在产生，但出于这样或那样的原因，它落在了裂缝之间。我认为最大的障碍是大多数FP写作没有针对阅读进行优化。

所以今天我想花点时间谈谈技术写作中常见的失败模式。如果你在发表帖子之前没有检查清单，你很可能会从内化这条建议中获益良多。

价值是多少？你会让人们更容易理解你想要告诉他们的东西。这就是你开始写作的原因，对吧？好消息是，所有这些都不是魔术--只是一些组织内容的简单指导原则。

这是最需要记住的一件事：你的读者并不真的在乎你要说什么。你可以用四句话来说服他们你的论文值得他们花时间。如果到那时你还没有提出你的理由，那么你很可能已经把他们丢到了他们大肆打开的下一个标签页上。

即使在你让他们相信这是一本有价值的书之后，你也需要继续向他们保证，你不是在浪费他们的时间。如果你花了太长时间才到达要点，或者如果你让信息在快速浏览中变得太难找到，那么你又一次迷失了它们。

因此，除了您的技术内容之外，您还有两个主要目标需要关注：

如果你能做到这两件事，你就已经在更好的参与度上走了很远。

人们关心的是问题的解决方案，或者希望有一天能有解决方案。他们也关心其他事情，但这对我们今天来说已经不是很重要了。

考虑到这一点，您需要根据问题的解决方案来调整您的动机。

以下是您可能遇到的一些很好的问题示例(以及指向它们的解决方案的链接，供您稍后阅读)：

激励文档的坏例子是那些仅仅因为它们的存在就认为你在乎的东西。这是图书馆教程中非常常见的。说服您使用一项技术的同一文档也应该向您展示如何使用。

作为一个更普遍的规则，关注为什么会比如何更有价值。

没有“为什么”的“如何”暗示了对一个虚构的问题的人为的解决方案。换句话说，它很容易被解读为“谁在乎呢？”

花大量时间阅读的人对于跳过大量文本有很好的启发式方法。如果你了解这些试探法，你就可以让人们很容易地找到他们正在寻找的东西。记住：他们正在寻找继续阅读的理由。

这里有两种行为。第一个是我所说的“略读概念”，即人们会试图从更高的层面上确定文本是关于什么的。他们在寻找你试图告诉他们的东西，而不是你实际说的话。

在略读时，人们可能只读一段的标题和前两句话。如果他们确信他们知道你要说什么，他们会跳到下一段。如果连续几个段落看起来不相关，它们将跳到下一个标题。

如果下一个标题也不能引起他们的注意，他们很可能会放弃。

解决办法是将你的论点组织成一棵树。标题必须提供足够的信息，让人们知道他们是否关心下面的散文。

这也意味着，每段的第一句话应该足以理解段落的其余部分。剩下的句子只允许加强第一句或给出第一句的细节。一段话等于一个想法。

也许你觉得很难知道假设你的读者知道多少知识。了解人们是如何阅读的，这就不是问题了。尽可能多地提供理解你的观点所需的信息，但如果人们已经知道了，就跳过它。那些还不知道的人会学习，那些知道的人可以跳过，两个阵营都会欣赏这一点。

在你让读者相信他们在乎你要说的话之后，他们会更愿意阅读你实际要说的话。当读者准备好一头扎进去的时候，你就可以更好地阐述你的论点了。

不太可能有人会读你文章的每一个字。更不可能的是，他们会按顺序把它们全部读完。

现在你已经让人们准备好倾听你的意见了，重要的是要让他们与你站在同一条战线上。你真的需要保持对任何可能分散他们注意力的事情的掌控。

使用短句。如果它太难解析，人们就不会这么做。

确保你的拼写和语法没有严重的问题。你不需要对这门语言有完美的掌握，但你需要能够发出信号表明你是值得信任的-足以让人倾听。不要低估拼写和语法的糟糕会让你失去多少可信度。

可能不那么重要的是，您还需要掌握概念上的绊脚石。如果你的论点跳跃了，感觉动机不佳，或者提到了一些潜在的不熟悉的东西，预计你的读者会感到眩晕。

我们在函数式编程中谈论的大多数想法都不容易，假装不是这样对任何人都没有任何好处。希望你的读者和你非常相似；如果你在理解你的主题时遇到了问题，那就把它说出来。指出障碍。指出他们可能在想什么，然后非常明确地告诉他们应该在想什么。

例如，如果您的代码样例使用函数依赖项，则可能值得用一句简短的句子来说明“有趣的条形图就是函数依赖项”。给出它的目的的一个很小的总结，并提供一个链接，让他们了解更多，如果他们需要的话。

另一个例子是：如果您最初感到困惑，认为“递归方案中的代数”与您在高中学到的代数不是一回事，那么您的读者可能也会感到困惑。当你第一次在新的语境中说“代数”时，你可以说“这是一个误导性的术语。这和你在高中时做的解方程式没有任何关系。“。

比你说的更重要的是你没说什么。如果你举的是符合某种模式的东西的例子，一定要给出不符合该模式的东西的例子。一个适用于任何地方的概念在任何地方都没有用处。

举很多例子。我认识的人都不会通过数学陈述来学习，也不会通过冗长、冗长、抽象的散文来学习。人们通过看大量的例子来学习，并被明确地告知这些例子是如何相互联系的。数学语句只有在您有直觉之后才有用，所以请将它们保存到适当的时间。

从这篇文章中得到的建议是，如果你想要很多读者，你必须让他们容易阅读。

为此，要非常注意动机。人们为什么要关心你要说什么呢？这对他们有什么价值呢？

把你的精力集中在开头--无论是整篇文章，还是每一段。那些不相信你的文章价值的人会快速浏览它，他们会通过只读事物的开头来做到这一点。

使您的信息易于查找。在树中组织您的参数，并确保它支持随机访问。没有人会把整件事从头到尾读完。相反，他们会跳来跳去，忽略他们已经知道的部分，寻找他们不知道的部分。

预测你的论点中哪些部分会让你的读者感到困难，并积极尝试缓解这些困难。举很多例子说明你在谈论什么，更重要的是，你没有在谈论什么。

指出你在学习这些东西的时候去了哪里。引导读者远离常见的错误和误解。

最后，以高音结束。给人们留下一种良好的感觉，这会激励他们深入了解你的下一篇文章。鼓舞人心的行动号召是一种走出去的好方式。

告诉他们你要告诉他们什么。那就告诉他们。最后，告诉他们你告诉他们的事情。