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

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

场景

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

现在网络上已经有很多写作平台了,让我们数数: 静态/动态博客(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/article/details/52083543
  • 插图
    如果说排版样式是外貌,那图片就像人的衣服一样,能为文章锦上添花。更何况还有 一图胜千言 的说法,可以避免读者在阅读时感到无聊。像是如果有流程图/原理图/时序图这些,将会显著的提高文章的层次。

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

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

总结

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