如何写好一篇技术文章?

时间:2022-01-27 14:49:09

文章整理自:

掘金YoungZ 、Github ruanyf、知乎 敖天羽


很多开发者都喜欢在各类社区平台分享一些写作内容,一方面可以对人生的一些经历进行记录,同时将开发中的经验总结分享给其他人。当然写作本身益处也是不少的,不仅能锻炼逻辑思维能力,还能训练日益退化的语言表达能力,个人影响力上也能够达到一定的传播积累。


但更多的开发者会问,文章到底怎么写?什么的样的文章可以得到别人的认可与喜爱?


在写一篇文章之前,先想清楚以下几个问题:


  • 这篇文章是写给谁看的?

  • 这篇文章主要讲些什么?

  • 文章具体怎么写?



给谁看


首先分析文章会给谁看,有了目标用户,你才知道需要产出一篇怎么样的文章。


比如,你的目标是小白用户,他们可能连 Node.js 都没有安装过,你上来就让他们配个 webpack 以达到什么目的,这多半是没什么指望了,你就得先告诉他们如何去安装 Node.js。


但如果你的文章面向的是更深层次的探讨和分析,为了这部分小白用户去增加篇幅大可不必,只会让那些中高级程序员觉得这篇文章废话连篇,原本的价值大打折扣。


实际上,一篇文章不可能面面俱到,所谓《从入门到精通系列》,即使是书,都是为了照顾新入门的准开发者们从零基础开始的,涵盖不了精通所需的很多东西。



写什么


文章内容的范围不宜过大,写大而全的东西对作者的水平要求非常高且需要消耗大量精力。如果真想写,也请先把思路理清,与有经验的人交流之后再下笔。


挑选的写作内容多是自己摸透了的东西,但是在细节上可能有模糊不清的地方。注意,你模糊不清的地方也正是许多人看此文的动机,务必查阅文献将此处叙述清楚!但又不可沉溺于细节之中,以能讲明白上下文为宜(更深入的细节适合另起一文)。另外,类似选型、对比、趋势一类的文章,对行业整体的把握也非常重要,在表达自己的观点之前,应该充分了解其它人的看法,尤其是和自己观点相左的看法。


一个小技巧是:在写文章之前,先把自己想写的主题用搜索引擎中搜一下,考虑自己是否有信心有能力超过已有文章。如果没有相关文章,那么可以先写入门级的内容,根据社区反馈逐步深入。



怎么写

技术文章的一大特点是文章逻辑严密,层级分明。因此在写作之前,应先列好提纲,根据内容层级由浅入深。


大部分技术知识可以用代码讲清楚,那么此处务必贴出代码。代码应该结构清晰,逻辑简单,能讲清楚问题就好了。一些关键代码需要有清晰的注释。如果有 demo,可以放上 demo 的链接。


在对高深内容或者细节进行描述时,即使前文已对相关名词做出了解释,也不应该堆砌专有名词。尽量用白话或者类比的形式将问题解释清楚,文字叙述不清楚的地方,请作图。



版面规范补充

字间距:全角中文字符与半角英文字符之间,应有一个半角空格。

错误:本文介绍如何快速启动Windows系统。

正确:本文介绍如何快速启动 Windows 系统。


全角中文字符与半角阿拉伯数字之间,有没有半角空格都可,但必须保证风格统一,不能两种风格混杂。

正确:2011年5月15日,我订购了5台笔记本电脑与10台平板电脑。

正确:2011 年 5 月 15 日,我订购了 5 台笔记本电脑与 10 台平板电脑。


半角的百分号,视同阿拉伯数字。

英文单位若不翻译,单位前的阿拉伯数字与单位间不留空格。

错误:一部容量为 16 GB 的智能手机

正确:一部容量为 16GB 的智能手机


半角英文字符和半角阿拉伯数字,与全角标点符号之间不留空格。

错误:他的电脑是 MacBook Air 。

正确:他的电脑是 MacBook Air。


文章句子,不包含任何标点符号的单个句子,或者以逗号分隔的句子构件,长度尽量保持在 20 个字以内;20~29 个字的句子,可以接受;30~39 个字的句子,语义必须明确,才能接受;多于 40 个字的句子,在任何情况下都不能接受。

避免使用长句。句子内部不使用逗号时,总长度不应该超过 40 个字;使用逗号时,总长度不应该超过 100 字或者正文的 3 行。

尽量使用简单句和并列句,避免使用复合句。


表示中文时,英文省略号(…)应改为中文省略号(……)。

英文:5 minutes later…

中文:5 分钟过去了……


英文书名或电影名改用中文表达时,双引号应改为书名号。

英文:He published an article entitled "The Future of the Aviation".

中文:他发表了一篇名为《航空业的未来》的文章。


总的来说,一篇优秀的技术文需要有:


•  取好标题,醒目突出中心

•  图文并茂,适当配图说明

•  篇幅适宜,不宜过短也避免冗长

•  格式统一,基本排版规则需要遵守

•  细节处理,错别字标点处理正确


LeanCloud正在发起线上征文活动,详情请点击活动海报  ↓ ↓ 


如何写好一篇技术文章?



end


LeanCloud,领先的 BaaS 提供商,为移动开发提供强有力的后端支持。更多内容请关注「 LeanCloud 通讯」

如何写好一篇技术文章?