如何编写一篇好的技术文章

吾辈的博客原文地址是 https://blog.rxliuli.com/p/3f...

场景

人的目标总是追求「优越性」，是要摆脱自卑感以求得到优越感。

现在网络上已经有很多写作平台了，让我们数数: 静态/动态博客（Hexo/WordPress），SegmentFault 专栏，简书，掘金，CSDN 博客。然而写作平台很多，愿意写作的人也很多，那么是否意味着我们就更容易获取知识了呢？其实并不是，原因在于很多人写作只是跟风，觉得很酷，所以用 hexo/hugo + github pages 建了静态站点发了一篇 hello world 之后就没有下文了。这种暂且按下不表，吾辈主要想说的是另一种：为了写作（积分）而写作，完全不用心，只是简单的把概念复制了一下，甚至直接抄袭别人的文章，不注明来源，而且没有尝试过文章做法的人。

这里强烈批评一下 CSDN 博客，虽然也有一些优质的博客，但更多的是直接 抄袭的文章，而且大多数都存在问题，实在令人深痛恶绝。甚至于，有人专门写了油猴脚本 google 百度搜索屏蔽 CSDN 用来屏蔽它，糟糕程度可见一斑。

思考

那么，真的想要开始写作，想要把自己的知识、感触和经验分享给其他人的话，有没有什么写作的技巧，或者说遵循的规则呢？下面是吾辈写作至今以来的一些经验，希望能帮到真心想要写作的人。

重点

• 是什么？
• 怎么做？
• 在哪里用？

细节

• 排版样式
• 插图
• 错别字
• 转发文章

重点

如果要写一个技术文档，那么有三点是必须要注意的。

• 是什么？
  可以是技术的一些简单介绍，或是在什么场景下会遇到这种问题，也可以是为什么要写这篇文章。就像吾辈，基本上每篇文章的正文都会有一个场景段落，用来介绍吾辈为什么写这篇文章，以及对涉及问题的介绍（吐槽 #打）。
• 怎么做？
  正确的描述具体如何使用，或是如何使用代码实现功能/修复错误。例如介绍 JavaScript Array 的文章，那就需要告诉读者如何使用常见的 API，例如 forEach, filter, map, reduce 这些函数，如何的使用它们，给出一些具体可运行的示例，如果有你觉得读者会难以理解的部分，更应该详细解释，并配上代码示例。
• 在哪里用？
  写作最有可能漏掉的部分，但却是最重要的。如果文章只是单纯罗列了一堆概念和代码，却不告诉读者在什么场景下才会用到，那么这只会是相当糟糕的文章，还不如去看官方文档（大部分文档都是告诉怎么做而不告诉在哪里用，尤其是某些 HTML/CSS 书籍，简直是把 MDN 的文档抄了一遍），至少还准确一些。

细节

• 排版样式
  读者进入网页之后，第一眼看到的绝对不是具体的内容，而是网页的排版大致是什么样子的，这点在读者阅读时能够清晰的感受出来。就像人的外貌，在开口前读者便能藉此看出大概（所谓以貌取人）。即便可能在读者继续阅读内容而扭转形象，但更有可能是读者直接点 X 关闭网页，并且留下了不好的印象。
  所以排版真的很重要，下面提供吾辈的几条经验:

  • 不要是纯 TXT 文本格式（大忌）
  • 使用代码块包裹代码片段，不要直接和普通文本一样，没有语法高亮看代码会死人的。
  • 合理使用标题。标题应该是逐级减小，而不应该出现一级标题，然后立刻就是三级标题，中间一定且必须有一个二级标题。
  • 文章中的链接应该是可点击的，并且最好引用一些比较官方的内容（MDN，Wiki）。
  • 错误示例: https://blog.csdn.net/xlxxcc/...

• 插图
  如果说排版样式是外貌，那图片就像人的衣服一样，能为文章锦上添花。更何况还有 一图胜千言 的说法，可以避免读者在阅读时感到无聊。像是如果有流程图/原理图/时序图这些，将会显著的提高文章的层次。

  附: 画图真的很花时间，如果有图片的话，说明作者是真的用心在写文章。（一般是大佬才会做，吾辈不是大佬，所以一般不会画图 #笑哭）

• 错别字
  但凡写作，如果有人说自己没写过错别字，吾辈是第一个不信的。人非圣贤，孰能无过。写作时出现错别字是很正常的，但由于人类本身的原因（参考 查出自己的错别字，为什么这么难？），所以想要检查是比较困难的 -- 但并不是毫无办法，我们在文章发布后，在网络上再次查看文章，会比在编辑器中更容易察觉到文章中的问题，这其中当然包含错别字。
• 转发文章
  当我们在网络上看到别人的文章，觉得写得很好，于是转发了文章想让更多人看到。但在转发之前，最好先询问一下原作者的意愿（一般是允许署名转载的），而且必须要在显眼的位置（文章顶部或尾部，一般最好是顶部）放置原文的链接，以使读者能够找到原作者。

总结

上面说了这么多，还有最后一句话要送给大家: 保持作者这个称呼的基本水平和对读者的基本尊重。