如何写出一篇优秀的技术文

2,119 阅读8分钟

大家好,我是张三岁🤣,一只法系前端⚖️。爱分享🖋️、爱冰冰🧊🧊。
欢迎小伙伴们加我微信:maomaoibingbing,拉你进群,一起讨论,期待与大家共同成长🥂。

前言

最近有小伙伴问我,之前没写过博客/文章该如何开始自己的写文之路。关于这个问题我思考再三,最终决定写一篇文章来分享我对 如何写出一篇优秀的技术文 的思考。

一、明确规范

无规矩不成方圆,做任何事都有其规范,写文章也不例外。首先,我们需要明确一些注意事项:

  • 杜绝不良内容
  • 杜绝敏感话题
  • 杜绝抄袭洗稿
  • 引用注明出处

相信小伙伴们的写作初衷都是对技术的热爱和对知识分享的渴望,所以也不会出现上述的问题,这里就不展开讲了。建议更文前自行翻阅掘金官方手册:《使用掘金:📐 掘金社区内容的标准和规范》

二、确定主旨

1. 明确的中心思想

写文章前要明确本文的中心思想,例如我想解决一个xxx问题,那就围绕这个问题来展开,如果有多个问题或者要讲述的内容,就要简单提炼一下,在前言总结概括,并拆分成多个章节段落。

2. 良好的文章标题

确定好文章的主旨后就可以开始构思文章名了,良好的文章名是文章最好的宣传。最好能体现出整个文章的核心技术栈或者解决问题的思路,毕竟技术文,主要还是以解决问题为主,看完你这篇文章能收获什么,读一下文章标题就能大致想到是最好的了。下面随机挑选了一些个人认为比较不错的文章标题。

首先登场的是简约式标题。此种标题能很直观的反映其主要内容,简洁而不简单:

或者你也可以考虑这种略带夸张式的文章标题:

当然,这种可可爱爱式的文章标题你也值得拥有:

3. 简洁的前言部分

优秀的文章一般都有前言/引言部分,一般用于介绍文章的主要内容,也会掺杂些许作者的个人观点,写这篇文章的心路历程等等。作为文章的非正式内容部分,前言的作用非同小可,毕竟读者看完文章封面紧接着就会看到前言部分,所以还是需要好好打磨的。前言是帮助留住读者的而不是把读者送走,良好的前言一般有如下特征:

  • 简洁明了,概括性强
  • 引经据典,吸引眼球

三、敲定框架

1. 何为“框架”

文章框架即文章整体结构,写完前言部分就得开始构思整个的文章的结构了,在这个阶段你需要根据你所讲述的内容进行段落的划分,如果内容较多还可以划分大的章节。不过不建议把文章弄得太长,文章过长容易使阅读者产生疲惫心理,可以把文章进行拆分,拆成上、中、下或者连载形式。

2. 如何划分

简言之,在开始写文章具体内容之前你的文章大体段落基本就出来了,然后再慢慢去填充细节部分。最好根据文章主要内容的主次、先后来划分。如果是分享代码块这种的就按照其类别进行划分,排序的优先级一般和其重要程度呈正相关;如果是解决问题这种的,就要按照步骤来划分,解决到一定程度划分一个章节,这样也方便读者进行进度回溯。下面是按照类别进行段落划分的示例:

  1. 一、分类 xxx(越重要或者越吸引人的往前放)
  2. 二、分类 xxx
  3. 以此类推...

如果是解决问题类的文章,则可以按照如下示例进行划分:

  1. 业务场景
  2. 实现思路
  3. 进行编码
    1. 编码过程第一步
    2. 编码过程第二步
    3. 以此类推...(最后要来一个总结)
  4. 问题发散

3. 合理的使用标题

一般情况下大的模块用一级标题,例如前言、参考资料、文章大的模块。然后大模块里面可以拆分出小的二级模块,此时使用二级标题,更细分的内容用更小的标题,以此类推。但是不能滥用标题,不然显得文章内容空乏,一眼望去全是标题;始终让内容占据主体(这里的内容主要指文字和代码)。其实完全可以在构建好一级标题之后去写内容,然后如果过于长了就拆分出来一个更小的模块。

四、完善内容

1. 精炼语言,提高阅读效率

写文章的时候,尽量精简一下文字(特别是修饰词),避免出现意思相近的多句话。就像写代码一样,能简写就简写(比如语法糖),当然也不要过度精简,太简单了阅读者反而容易看不懂。如果你有一个概念需要介绍,其实可以把详细的部分单独拿出来作为一个小段分隔开,然后再前文增加说明如“熟悉者可跳过”等字样。

2. 规范代码,降低阅读成本

2.1 首行说明

在翻阅了众多优秀文章后,我发现大多数作者都会在代码块的首行添加注释,标明是哪个文件,例如:utils/index.jsModuleName/index.less 。这样做的好处是便于读者理解与日后翻阅。

// utils/index.js 标明这是哪个文件
// 具体代码...

2.2 代码格式化

在把代码块粘贴到文章之前,一定要用编辑器(如 VScode )格式化一下代码,避免出现那种代码排版错乱的情况。(代码格式强迫症患者看到都说好)

这里就推荐两款 Vscode 的代码格式化插件:BeautifyPrettier - Code formatter

Beautify.png Prettier - Code formatter.png

3. 精美配图,缓解阅读压力

当文章的某一个段落文字过多时,往往会增加阅读者的阅读压力,也更容易劝退读者(想想那种大段大段的文档)。除了根据需求拆分成更小的段落以外,还可以适当增加配图。配图一般有如下类型:

  • 思维导图系列
  • 截图(一般是代码运行结果演示)
  • 插画/海报

思维导图可以直接使用编辑器自带的,或者使用软件 XMind 进行制作,包括其他图也一样,例如流程图、甘特图等,都是对文字进行辅助说明,或者对内容大纲进行分类的。下图来自 XMind 官网:

思维导图.png

这里的截图是指对文章所述的功能或操作流程进行屏幕截取,来更清晰的展示代码的运行效果,或者更明白的演示某个操作流程。当然有时候用 GIF 动图的效果会更好。下面推荐几个截图工具:

最后说一下文章的封面,有条件的可以自己制作封面,根据文章的内容制作对应的图片,一个系列的文章可以用相似的文章封面加以对应。当然,选用壁纸或非商用海报也未尝不可。

4. 整理排版,提高阅读体验

当文章的内容逐渐充盈起来时,良好的排版就显得越发的重要了。我们可以参照以下的方法进行优化:

  • 图片、代码块前后留好间距
  • 一段文字过长时,用空行进行分割
  • 使用 有序列表无序列表 代替冗长的文字

五、检查错误

当写完文章后,就需要进入检查错误阶段。检查错误主要是对一些关键的地方进行勘误,毕竟文章在显著位置出现了问题难免会很尴尬。根据其重要性,检查错误大致分了几个步骤:

  1. 检查文章标题和一级标题有无错别字
  2. 检查文章前言部分有无错别字和病句
  3. 检查文章中的链接是否可以正常打开

六、回溯全文

在上一步骤中已经对各级标题、前言等关键位置进行过检查,那么发文前的最后一个(可选)步骤就是进行全文通读。这一次要把自己代入阅读者的身份,排查文章中可能存在的表意不明,语句不通顺的问题。通常,写文章是作者把自己的想法用文字进行表述,难免会出现口语化的现象。在日常开发过程中,可读性强的代码往往更受欢迎,同样的道理,写文章也应该让它更容易被读者接受。