《技术写作指南》笔记
小册《技术写作指南》的笔记,只摘抄整理方法论部分的,方便日后翻看。
这是小册地址,阅读后确实感觉收获颇丰,大佬的文笔以及各方面知识的输出都非常棒。 s.juejin.cn/ds/Sjc24qt/
确定写作选题
技术写作的选题分成了下面八类:
- 新方法、新特性、新技术;
- 日常工作中的小技巧,小创新;
- 深入理解XXX,XXX原理剖析;
- 技术实现方案综述、技术选型对比;
- 体现技术深度的棘手问题解决;
- 框架、工具、会议体验指南不指北;
- 外文翻译;
- 技术资讯与技术人文。
选题 2、3、5 则特别适合对技术有追求的同学,且一定要多写,收益斐然!
确定写作内容
- 参考文档:新特性
- 固定素材:定期素材,比方说知名框架或者知名工具的新版发布,优秀的开源项目
- 订阅周刊:通过关注周刊的方式了解最新的行业动向以及一些精妙的技术实现,尤其是国外的周刊
- 佛系随缘:刷微博,逛朋友圈,写代码时候想到的点子
- 工作实践:
- 遇到的困难
- 用了没用过的技术和实现
- 引用外部的组件或者工具
- 项目完成后的成长和复盘
如何给文章起标题
- 文要对题,内容为王
- 文如其人。符合自己的风格,嘻嘻哈哈、一本正经或者坦诚务实都可,保持一致(强化个人形象)
- 访问来源。人类普遍感兴趣的东西都是类似的,八卦、钱、异性,技术文章则尽可能出现动作、数字、吸睛词(即热点、流行事物),句式上可以疑问、感叹,但注意语气不要太强烈,技术群体的读者都比较理性,不吃这一套。
- 平台智能生成标题功能
如何搭建文章框架结构
连贯性
-
结构有序。(让枯燥的文章更耐读)
-
具有连贯性的事物还有很多,例如数字一二三,方位上中下,从头到尾,从理论到实践等。典型的是时间顺序
比方说介绍某个浏览器新支持的 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...
-
换位共情,避免写出来的内容晦涩难懂,把自己想想成一个小白进行问题的探究
-
内容严谨,不清楚要进行代码自测
-
技法高明
- 尽量的口语化
- 适当地使用疑问句或反问句。
- 可以适当的停顿或重复来表示强调。
注意,注意,注意,重要的事情说三遍,千万不要...
- 善用比喻,学会举例。