本文字数:3536

预计阅读时间:6分钟

背景

最近团队有同学提议,想探讨如何才能写出一篇优秀的技术文章。所以尽管水平实在有限,还是按照自己的经验和理解写下了这篇文章,亚历山大之余,也很高兴和大家分享一下自己对技术写作的一些思考。

希望本文可以抛砖引玉,大家从中可以有所思考和收获,就能达到本文的目的了。那么,写好一篇技术文章对我们有什么用呢?

我觉得有三点:

  • 第一点,可以更好地分享传播技术方案,让读者认同赞赏你的文章;

  • 第二点,通过文字表达提升个人的表达能力,在做技术分享和演讲时提升效果及魅力;

  • 第三点,通过整理技术文章,主动对技术深入思考剖析,提升个人的技术广度和深度能力。

那么,接下来我重点分享下我实践中的写作流程。

写作流程

写作流程,大体上可以分为:写作前的准备工作、写作中的注意事项和技巧以及写作后的提升工作。

通过对这三个阶段的打磨,相信你就可以写出一篇“令人满意”的技术文章。

写作前

所谓万事开头难,所以写作前的充分准备工作,可以帮助你快速进入写作状态,准确明晰写作内容。让我们通过以下手段,告别写作开始时的“提笔皱眉”,体验一把“下笔如有神”。

确定立意标题

我认为立意和标题应该是先确定清楚的,要非常明确地知道自己要写什么内容,这个“什么”其实并没有那么简单确认,可以参考以下罗列的确认要素:

  • 内容传达的目的是什么?

  • 内容关键字是什么?

  • 内容触达的范围是什么?

  • 内容的重点是什么?

最后,通过对立意的分析思考,形成一个立意明确的标题。不要小看这个标题,这个标题是文章的“门面”,有时候甚至会让读者使用“一票否决权”。所以,标题也应该首先明确下来,在写作中不断围绕立意的标题进行,这样即不会产生跑题的情况,也对内容进行了充分强化。技术文章的标题,其实不用起得那么“八卦”来吸引读者,简单直接即可。可以参考以下罗列的标题要素:

  • 紧扣内容立意

  • 简短清晰

确认目标读者

确认目标读者是非常重要的,尤其文章需要在一些特殊场合中进行发布和使用。是分享技术到社区?还是给领导汇报技术方案?还是具体下发开发执行方案?不同的场景,写作的侧重点和用语都需要做相应的调整。至于如何调整,这个需要对不同的环境进行判断,并不能一概而论,可以参考不同场景下要考虑的写作要素:

  • 文章中的称谓

  • 读者最关心的是哪部分?过程?结果?还是数据?

  • 是否需要为读者提供某些补充资料?

形成树形提纲

在确认立意和目标读者之后,我们就可以开始“下笔”了,但是我建议不要急于写文章的主体部分,而应该先形成纸面的“树形提纲”。当然,如果写作前脑子里的“布局”就已经非常清晰,也可以省略纸面工作。其实,我们写文章,尤其是比较长的文章,是应该有目录索引的,这样非常方便读者检索。而这个步骤正好同时完成了目录整理的过程:只需对树形提纲进行适当提炼,就可以轻松成为我们的目录索引了。可以参看本文的目录索引,其实也就是本文的树形提纲了。

准备周边素材

巧妇难为无米之炊,没错,提纲有了就相当于锅碗瓢勺等吃饭的架子都已准备妥当,就差最重要的“食材”就可以“做饭”(写作)了。因为我们已经有了立意和树形提纲,围绕它们我们就可以明确知道接下来要写什么内容,那么拿什么来支撑内容呢?可以参考以下可以准备的素材分类:

  • 关键概念

  • 关键代码

  • 规范要求

  • 案例支撑

  • 图片解释

互动demo

其实周边素材可以有很多,在前期准备的时候可以“贪多”,最后再进行“过滤”即可。而收集素材、审视素材的时候,会促进我们来来回回地进行学习和思考。这个过程对作者来说是十分有益的,不仅能把自己的经验沉淀在纸面上,也同时在这个过程中不断“验证”、“证伪”、“升华”自己的技术经验,甚至碰撞出一些令人激动的“思维火花”。

调整树形提纲

从树形提纲形成之初,它就可以不断进行调整。不管在准备周边素材还是在写作中或写作后,都可以在当下按照自己的理念进行调整,或裁剪或丰满。这有点儿像我们写程序时,不断调整参数以观察不同的输出结果,直到结果令人满意,那么树形提纲就“定型”了,与之关联紧密的“目录索引”也可轻松产出。这样我们就可以有条不紊地开始写作了。因为我们手里有了“树形提纲”这个写作向导,就不用再为不知道写什么,不知道是不是跑题了而烦恼。

写作中

我们顺着“树形提纲”有条不紊地进行叙述就可以进行文章主体部分的写作了。但有的同学可能依然会感到困惑,还是不会写怎么办?其实这里我认为涉及到一个写作能力和技巧培养的问题。写作能力的培养绝不是一朝一夕的事情,所以这里简单地抛砖引玉,从写作基本功、技术难点阐述以及提炼方法论这三个方面,简单说下我对技术写作的理解。

写作基本功

写作基本功其实是我们从识字开始就不断练习的一种技能。我们平时读文章,常常会感叹有些作者的文笔很好。其实好的文笔一定是建立在良好的写作基本功之上的。市面上有很多专门的书籍和课程来讲怎么写作,我们可以专门去学习这门“技艺”,当然多看多练多模仿是少不了的,这里就不再展开这些内容,主要列下需要注意的点:

  • 格式:段落、标点、字体、字号、数字等

  • 语法:主谓宾、转折、关联等

  • 段落:总分、层次、点题等

  • 逻辑:清晰、自洽、完整、无歧义、用词统一等

  • 对仗:时间对仗、层次对仗、递进对仗等

技术阐述技巧

这里重点提一下技术方面的阐述技巧,因为我们写的是冷冰冰的代码,它本身没有过多的“人性”,而技术文章的使命就在于此,让读者不必“过深”地阅读代码,就可以从代码那“百折千回”中领悟到你的“意图”。一篇好的技术文章往往就是在这个环节做得非常出色,总是能让读者轻松领悟到代码意图,如果能让读者发出:“原来是这样!cool!”如此的感叹,那就是好的技术文章所带来的魅力了。技术难点的阐述的难度往往是由技术本身的难度带来的,因为“晦涩难懂”的代码转化成“通俗易懂”的文字,是需要极强的技术能力和文字表达能力的。那么除了能力的培养提高之外,有没有什么方法可以让我们在写技术难点时更有指导方向呢?下面我列举了几种方法,供大家参考。

举例法

常用的手段之一就是举例子,通过通俗的例子来解释代码逻辑。例如数据结构queue(队列)stack(栈),我们就可以生活化地解释它们。

queue:就是在排队在“鲍师傅”窗口买蛋糕的队伍,先来的人买完之后先离开,这对应着queue中的值先进先出的特性。

而stack:就是“老鹰抓小鸡”中的队伍,老鹰要从队伍尾巴处把人一个一个抓出去,这对应着stack中的值后进先出的特性。

举例子其实有很多手段,可以举生活的例子,也可以举复杂代码简化后的例子,还可以跨学科举例子。只要有利于读者通俗易懂并准确get到核心的例子都是好例子。

重点突出法

很多时候,技术文章因为技术点很多,而删减技术点又不利于整体阐述。这时候,重点突出法非常管用。因为在茫茫的大草原中让别人发现一颗稀有的小草太难了,那我何不在这颗重要而稀有的小草旁边立块牌子,并写上字“嘿!看过来,我在这!”呢。对于文章想要强调的重点,一定要重点突出出来,怎么可以突出呢?可以参考以下手段来突出重点:

  • 相关重点给予足够的篇幅

  • 单独成段

  • 提炼小标题

  • 视觉加强:加粗、字体颜色、增加背景色等

图像法

一图胜千言,绝非虚言。读者对图的直接感知度往往要比干巴巴的文字要强很多。一张好的图可以解释大段文字才能说清楚的东西,甚至文字无法表达的“意境”同样可以使用图来“表意”。但是前提是图是精心设计并准确表意的,如果滥用图或者图使用不得当则会适得其反。即使我们不知道画什么,计算机领域里也依然有迹可循,由于图强大的解释力,软件开发中层出不穷地建立了很多有关“图”的规范:UML、流程图、实体图、数据流向图、原型图等等。善于利用这些图会使得我们的“技术解释力”更上一个台阶。

交互法

交互法和举例法有些像,但是举例法大多是“静态”的,而交互法则更具生命力,它是可以“动态”交互的。例如我们在阐述多个实体的关联关系的时候,我们可以提供给读者一个交互动画,让读者用连线的方式来理解实体间的关联关系,这种让读者主动参与到技术学习中的方式,往往比被动地接受有用得多。交互法虽然制作成本大,但对于教学类的文章是效果非常好的阐述和演示工具。

提炼方法论

当我们写完文章主体部分后,写一个让人印象深刻的总结是非常有必要的。而这个总结得广度和深度是可以发散的,也就是说可以从文章的点形成总结的面,从文章的面形成总结的体。从文章本身抽象到某个领域的通用规则,也就是提炼方法论。当然,我非常不建议强行提炼,而当这篇文章真的激发了你的深度思考并有所结论时,快,千万别犹豫,把它总结提炼出来,这对于作者本人和读者都将大有裨益。

写作后

当文章的主体写作完毕,还是有一些方面需要继续处理,这里重点讨论三个方面。

通读找错

写完文章,需要通读文章,并在通读的过程中寻找错误,例如错别字、不通顺语句、表意不明等。

查漏补缺

在通读文章的过程中,继续查漏补缺,多余的删除,没阐述完整或清晰的则需要增加。另外如果你的文章引用了规范、他人著作等,一定要加上引用说明,一来遵守被引用方的版权,二来为想要深入引用资料的读者提供检索便利。

升华立意

升华立意在技术文章中的确不多见,但是在某些特定场景下则可使文章更具“饱满感”,例如把技术文章和公司战略、技术前沿突破等方面结合起来,会使得技术文章同样可以“发光发彩”和“走进人心”。

结束语

其实如何写好一篇技术文章这个问题的答案很简单:技术好 + 写作好。而本文着重阐述了我对如何“写作好”的看法与总结。而这些大多都是“术”,想要达到更高境界,必须要悟“道”:培养自我独有的感悟能力。

那么如何才能“悟道”呢?我也还在悟的路上,这里分享三个个人看法:

借他山之石:站在高手的肩膀上,多学习借鉴他人的写作手法和思路,取其精华去其糟粕。

行自我之思:勤思考多总结,自我思考得够多够深,才不会“思到用时方恨少”。

走勤奋之路:万丈高楼平地起,一点一滴积累,勤耕不辍。

由于本人能力所限,请大家对本文不吝指正,望共同进步。

程序员如何写好一篇技术文章?相关推荐

  1. 如何写好一篇技术文章

    技术文章是能够有效锻炼表达能力和进行技术积累的方法.与单纯的技术笔记不同,我认为的技术文章应该是对实际的问题或新技术思路的解决方案,而不是技术点的简单堆砌. 对于如何写一篇我认为合格的技术文章, 最近 ...

  2. 我写的几篇技术文章之一:Windows消息拦截技术的应用

    Windows消息拦截技术的应用<?xml:namespace prefix = o ns = "urn:schemas-microsoft-com:office:office&quo ...

  3. 国内第一创作平台大佬,教你如何写好一篇技术博客?

    码个蛋(codeegg) 第 975 次推文 作者:九心 链接:https://juejin.im/post/5ec29c16e51d454d9b12677f 前言 很多同学的进阶都是从写文章开始的, ...

  4. 程序员如何写好技术简历 —— 实例、模板及工具

    by @Easy 前言 光是做人才拍卖这几个月,我就看了几千份技术简历,觉得很感慨.有太多程序员因为不知道如何表达自己,而埋没了自己的才华,拿着原本可以拿到一半的薪资,在一家默默无闻的公司里边加班到深 ...

  5. 程序员如何写出技术好文?

    本文作者是阿里巴巴淘系技术 2020 年度作者,在内网论坛写文,写一篇爆一篇.分享一下他写文章时用到的一些小技巧,希望对大家有帮助. 最重要的是内容 和所有人强调的一样,好文章最重要的是要有好的内容, ...

  6. 技术总监谈好的程序员如何写代码[转]

    技术总监谈好的程序员如何写代码[转] 要判断一个程序员是不是好的程序员,主要看他写的代码,因为程序员最重要的事是写代码.          即便不去理解代码的意图,只要看一眼,好的程序员写的代码与差的 ...

  7. [转]为什么程序员总是写糟糕的代码?这3个原因

    原文请看:为什么程序员总是写糟糕的代码?这3个原因 我最近一直在想我们作为一个行业为什么总是产出糟糕代码的原因. 1.明显原因-- 我一下子想到的最明显的原因是,有好的程序员,也有不那么好的程序员,有 ...

  8. 每个程序员都必读的10篇文章

    作为一名Java程序员和软件开发人员,那些每个程序员都应该知道的XXX的文章教会了我不少东西,它们提供了某个特定领域的一些实用的并且有深度的信息,这些东西通常很难找到.在我学习的过程中我读到过许多非常 ...

  9. 每个程序员都必读的12篇文章

    作为一名Java程序员和软件开发人员,那些每个程序员都应该知道的XXX的文章教会了我不少东西,它们提供了某个特定领域的一些实用的并且有深度的信息,这些东西通常很难找到. 在我学习的过程中我读到过许多非 ...

最新文章

  1. node简单实现excel文件下载
  2. 详解阿里开源分布式事务框架Seata
  3. 风电功率预测matlab,一种基于二十四节气的风电功率预测方法与流程
  4. C#断点续传原理与实现
  5. 如何在SQL Server 2019中添加数据敏感度分类的命令
  6. c语言 静态链表插入排序,数据结构 - 表插入排序 具体解释 及 代码(C++)
  7. 2.4 在不同的划分上进行训练并测试
  8. python根据频率画出词云_利用pandas+python制作100G亚马逊用户评论数据词云
  9. mysql主从复制浅析(一)
  10. 信号与系统速成和课后作业
  11. Java 冒泡排序的使用
  12. Core、处理器(CPU)核、处理器(CPU)、处理器(CPU)架构、微结构、指令集、指令集架构、ARMv7 内核架构
  13. EF中的Guid主键
  14. 净资产收益率与市盈率的关系
  15. 【JUC】008-Stream流式计算
  16. Ubuntu小技巧14--sed命令详解
  17. “天翼阅读”APP用户体验
  18. 如何使用repo管理本地私有仓库
  19. 罗升阳对安卓2.3系统的总结
  20. linux antivir,Linux下安装和使用杀毒软件AntiVir (2)

热门文章

  1. QTableWidget 常见用法总结(一)
  2. React + TypeScript实战(二)hooks用法
  3. 吴雪筠校友报告会 --职场仪表—心态—自强之道
  4. 给开源社读者的一份信
  5. 华为AC+AP上线配置
  6. Android 穿过点画平滑曲线
  7. 2021计算机保研夏令营经验分享——上岸中科大大数据学院
  8. 需求分析阶段的各个步骤
  9. 学习笔记(28):MATLAB基础入门课程-乘方运算
  10. 小 200 行 Python 代码做了一个换脸程序