《技术写作指南》笔记

253 阅读7分钟

《技术写作指南》笔记

小册《技术写作指南》的笔记,只摘抄整理方法论部分的,方便日后翻看。

这是小册地址,阅读后确实感觉收获颇丰,大佬的文笔以及各方面知识的输出都非常棒。 s.juejin.cn/ds/Sjc24qt/

确定写作选题

技术写作的选题分成了下面八类:

  1. 新方法、新特性、新技术;
  2. 日常工作中的小技巧,小创新;
  3. 深入理解XXX,XXX原理剖析;
  4. 技术实现方案综述、技术选型对比;
  5. 体现技术深度的棘手问题解决;
  6. 框架、工具、会议体验指南不指北;
  7. 外文翻译;
  8. 技术资讯与技术人文。

选题 2、3、5 则特别适合对技术有追求的同学,且一定要多写,收益斐然!

确定写作内容

  1. 参考文档:新特性
  2. 固定素材:定期素材,比方说知名框架或者知名工具的新版发布,优秀的开源项目
  3. 订阅周刊:通过关注周刊的方式了解最新的行业动向以及一些精妙的技术实现,尤其是国外的周刊
  4. 佛系随缘:刷微博,逛朋友圈,写代码时候想到的点子
  5. 工作实践
    • 遇到的困难
    • 用了没用过的技术和实现
    • 引用外部的组件或者工具
    • 项目完成后的成长和复盘

如何给文章起标题

  1. 文要对题,内容为王
  2. 文如其人。符合自己的风格,嘻嘻哈哈、一本正经或者坦诚务实都可,保持一致(强化个人形象)
  3. 访问来源。人类普遍感兴趣的东西都是类似的,八卦、钱、异性,技术文章则尽可能出现动作、数字、吸睛词(即热点、流行事物),句式上可以疑问、感叹,但注意语气不要太强烈,技术群体的读者都比较理性,不吃这一套。
  4. 平台智能生成标题功能

如何搭建文章框架结构

连贯性

  • 结构有序。(让枯燥的文章更耐读)

  • 具有连贯性的事物还有很多,例如数字一二三,方位上中下,从头到尾,从理论到实践等。典型的是时间顺序

    比方说介绍某个浏览器新支持的 JS 属性,如果走时间线策略,那么可以这样设计:

    我今天逛掘金

    偶然看到了个JS属性

    居然没见过

    成功地引起了我的注意

    于是上去试探了下

    呵,没想到这个属性还是个磨人的小妖精

    故纵欲擒吗?那我就陪你玩到底

    没想到你是这样的属性

    该死,我好像爱上这个JS属性了

  • 强制连贯。

    强制连贯多出现在上下内容偏差较大,风格不一,明显不连贯的场景下。就是用语言将上下文串起来,防止突兀。

  • 强制中断

    善用分隔线

突出性

  • 文章的脉络清晰,重点突出(目录)

  • 如何突出重点

    三个要点:标题、位置和篇幅

    操作也很简单:

    • 要点标题需体现;
    • 亮点位置可靠前;
    • 重点篇幅不设限。
  • 举例

    • 突出技术(对应技术写作中的技术介绍)

      标题:我遇到的 JS 属性...

      这个JS属性可是个磨人的小妖精

      欲情故纵,还会玩火

      成功激怒了我

      深入交流后发现竟然这般甜美

      首先她……

      然后她……

      再者她……

      最后她……

      万幸,今天逛了掘金

    • 突出故事(对应技术写作中的人生轶事)

      标题:我今天遇到个很棒的事情

      今天逛掘金

      竟然找到了让我心动的JS属性

      怎么回事呢?

      我本来……

      没想到拒绝我

      很好,你已经成功地引起我的注意了

      我就继续试探

      ……

      我就说过,你早晚都会是我的

    • 突出自己(对应技术写作中的难题解决)

      标题:看我如何搞定...

      这种事情也就我能做到

      这个JS属性是个磨人的小妖精

      要想拿下可不容易

      我就想着……

      于是决定……

      结果却挑战我的底线

      不能放弃,再次……

      这下终于……

      看,多么甜美!

      学我,你也可以!

具体写作套路

技术科普类型

graph LR;
	
    start("作用是什么?") --> show("效果演示(如果有)")
    show --> basic("语法和参数")  
    basic --> content("具体使用说明(案例)")
    content --> addition("细节知识(包括兼容性)")
    addition --> conclusion("点评总结")
    
    subgraph 亮点前置
		start
    end
	subgraph 主要篇幅
    	content
    end
    subgraph 稀缺内容
    	conclusion
    end

原理剖析类型

遵循由表及里,层层深入的架构策略,方便他人的学习与理解。

graph LR;
	
    start("现象描述") --> show("现象展示")
    show --> explain("解释说明")  
    explain --> content("更深入解释")
    content --> conclusion("启示与拓展")
    
    subgraph 视频或图片
		show
    end
    subgraph 基本概念/浅层原因
		explain
    end
	subgraph 体现专业深度
    	content
    end
    subgraph 稀缺内容
    	conclusion
    end

功能实现类型

一定要放代码,最后配上演示页面,然后为了吸引用户继续阅读,通常会把实现好的效果放在最前面。

graph LR;
	
    start("功能/效果说明") --> show("效果演示")
    show --> idea("实现思路")  
    idea --> code("实现代码")
    code --> principle("实现原理")
    principle --> conclusion("总结与拓展")
    
    subgraph 在线demo/视频/截图方式
		show
    end
    subgraph 读者最关心部分
		code
    end

使用教程类型

graph LR;
	
    start("背景说明(如果有)") --> step1("步骤1/操作1")
    step1 --> step2("步骤2/操作2")  
    step2 --> step3("步骤3/操作3")
    step3 --> stepX("...")
    stepX --> conclusion("其他说明")
    
    subgraph 注意事项/示意图
		step1
		step2
		step3
		stepX
    end

问题解决类型

graph LR;
	
    start("背景描述(如果有)") --> question("问题描述")
    question --> show("问题演示") 
    show --> idea("我的思考")
    idea --> try("初次尝试")
    try --> result("结果")
    result --no--> idea
    result --yes--> conclusion("结语")
    
    subgraph 视频或图片
		show
    end
    subgraph 非常重要
		idea
    end
 

项目总结类型

本质上就是一种职场邀功炫技手段,关键是如何通过不会让人反感的朴实无华的语言透露出项目牛逼、项目人员牛逼的信息。

graph LR;
	
    start("项目背景") --> score("取得的成绩")
    score --> pay("个人/团队的贡献")
    score --> question("个人/团队的困难与解决")
    score --> grow("个人/团队的成长")
    conclusion("启示与拓展")
    pay --> conclusion
    question --> conclusion
    grow --> conclusion
    conclusion --> thank("感谢")
    
    subgraph 漂亮的数据或最终效果
		score
    end
    subgraph 项目详情--根据实际情况调整
		pay
		question
		grow
    end

会议记录类型

graph LR;
	
    start("会议简介") --> show("现场照片(如果有)")
    show --> step1("过程1")  
    step1 --> step2("过程2")
    step2 --> step3("过程3")
    step3 --> stepX("...")
    stepX --> conclusion("自己的感受")
    
    subgraph 时间和参与人等
		start
    end
    subgraph 按时间顺序描述并点评
		step1
		step2
		step3
		stepX
    end

工具测评类型

比方说某某框架初体验、A 框架和B 框架我该使用哪个?

这类文章的核心价值就在于评测,你以一个过来人的身份,是否建议读者使用这个工具之类的。

但评测是否中肯可信,还需要一些证明,这些证明就可以通过展示使用过程和最终效果来完成。

graph LR;
	
    start("故事背景") --> process("使用过程全记录")
    process --> feeling("使用感受")  
    feeling --> evaluate("优点是?缺点是?")
    feeling --> compare("和同类工具对比如何?")
    feeling --> future("对其未来发展的判断是?")
    
   	conclusion("最后的总结")
    evaluate --> conclusion
    compare --> conclusion
    future --> conclusion
    
    subgraph 为什么会使用此工具
		start
    end
    subgraph 视频或截图
		process
    end
    subgraph 核心价值
		feeling
    end

技术人文类型

技术人文类型写作范围非常广泛,例如软技能分享、心理困惑答疑、职业发展指导、行业发展看法等都属于技术人文的写作范畴

观点类的技术文章的写作结构:

graph LR;
	
    start("论点先行") --> reason1("原因1")
    reason1 --> reason2("原因2")  
    reason2 --> reason3("原因3")
    reason3 --> reasonX("...")
    reasonX --> conclusion("最后的总结")
    
    subgraph 我认为...
		start
    end
    subgraph 案例佐证
		reason1
		reason2
		reason3
		reasonX
    end

职场故事类型

当事人的真实经历,按照时间线讲好每个时间段的故事即可

graph LR;
    	
    start("故事背景") --> step1("做了什么事")
    step1 --> step2("发生了什么结果")  
    step2 --> step3("当事人的感受")
    step3 --> stepX("再后来...")
   

如何制作配图及相关素材

代码

优先使用代码块功能。技术文章中的代码块务必要精简,除非是专门提供给读者复制用的完整代码。

配图

技术文章的配图大致分为这几种:示意图、表情图和视觉图。

软件推荐: FastStone Capture 进行截图、FigJam绘制流程图还是逻辑图、screenToGif技术写作最友好的录屏工具

在线演示

● 如果是偏视觉、偏交互效果的在线演示,推荐使用 codepen.io/ 这个平台。

● 如果是 JS 代码运行,可以试试jsbin.com/这个站点,优点是即开即用,非常爽气,缺点是好久没更新了,对于新特性的识别有问题,适合纯 Web 演示。 还有个同时期的名叫jsfiddle.net的网站,这个网站并不推荐用在技术写作中,因为不知道触犯了哪条红线,国内访问一直有问题。

另外,jsbin 还有个非常哇塞的优点,就是其本身是个纯开源的项目,可以零成本搭建在自己的平台或者公司内部。

● 如果运行代码依赖于框架或环境,可以试试 codesandbox.io 这个平台,不仅支持纯 JavaScript 的运行,还可以模拟在 Vue、React/Preact、Svelte 等框架,或者在 Node.js 等环境下的运行。

● 如果是 Node.js 运行,也可以考虑runkit.com/ 这个平台

怎样写出更有吸引力的内容

  • 稀缺性,稀缺的知识、技术、代码是核心竞争力

  • 形式创新,主要指导将文章用新颖的方式表达,比如配合ChatGPT

  • 角度新颖

    描述数组遍历的几种方法是老生常谈。

    但是从新颖的角度能给文章带来吸引力

    • 以数量为切入角度:我一共知道 12 种数组遍历方法,你知道几个?
    • 以对比为切入角度:for/for...in 和 for...of 有什么区别?
    • 以性能为切入角度:常见 JS 数组遍历方法速度测试
    • 以使用场景为切入角度:日常开发,我该使用哪个数组遍历方法?
    • 以技术 Tips 为切入角度:forEach 不支持 break?试试使用 some/every 方法进行数组遍历
  • 棱角个性,带有个人情感,以自己或他人为视角进行描述。抒发个人的情绪,表达个人的见解。

    对比:

    ​ 数组遍历有如下方法:1, 2, 3...

    ​ 我今天才知道,数组遍历原来有这么多方法:1, 2, 3...

  • 换位共情,避免写出来的内容晦涩难懂,把自己想想成一个小白进行问题的探究

  • 内容严谨,不清楚要进行代码自测

  • 技法高明

    • 尽量的口语化
    • 适当地使用疑问句或反问句。
    • 可以适当的停顿或重复来表示强调。注意,注意,注意,重要的事情说三遍,千万不要...
    • 善用比喻,学会举例。