科技爱好者周刊(第 288 期):技术写作的首要诀窍

作者: 阮一峰

日期: 2024年1月26日

这里记录每周值得分享的科技内容,周五发布。

本杂志开源,欢迎投稿。另有《谁在招人》服务,发布程序员招聘信息。合作请邮件联系[email protected])。

封面图

在昔日的"皇家园林"北京颐和园,昆明湖已经完全结冰,变成了游人玩乐的大冰场。夕阳西下,湖上的十七孔桥现出了"金光穿洞"景观。(via

技术写作的首要诀窍

技术写作非常重要,产品的开发、推广、维护都需要它。

跟大家想的不一样,技术写作的好坏,跟语文水平关系不大,更多是一个技巧问题

因为技术写作的评价标准,不是艺术性,而是表达是否清楚明白。它不需要华丽的词藻、巧妙的比喻、深刻的感悟,只需要把问题说清楚。

把问题说清楚的关键,在于你的思想是否清楚。

当你想清楚了一个问题,只要掌握几个基本诀窍,就能写出一篇很好的技术文章。

今天,我来说说,技术写作的首要诀窍是什么。很简单,就是一句话:文章采用单线结构

所谓"单线结构"(也称"线性结构"),指的是一篇文章只说一件事,按照线性顺序进行叙述,由浅入深、循序渐进、平铺直叙、层层递进。

这就好比一个游览区,只有一条游览路线,从入口到出口,跟着箭头一路走,就能看到所有景观,非常明白清楚。

如果同时有好几条路线,游客就会糊涂,到底选哪一条?会不会错过景观?要是这些路线还互相交叉,那就更糟糕了,游客非串线不可。

(图片说明:上面的景区路线图,应该选择哪条路线吗?)

只要采用了单线结构,技术文章就不会太差。即使内容是难懂的,至少结构是清晰的,一环扣一环,读者能知道自己卡在哪一环上。只要克服了这个难点,就能继续往前走,不会有陷入迷宫、找不到方向、如坠五里雾中。

有一篇老外的文章,使用图形表示文章结构,非常形象。

上图就是单线结构,按照箭头,一步步推进。

有的问题比较复杂,涉及多个因素,可能是星状结构。

也可能是"层次结构"。

这时,建议把这个问题拆分成多篇文章,每篇文章保持单线结构,坚持做到一篇文章只讲一点,而且争取把这一点讲透。

但是,单线结构说起来容易,做起来难。难就难在,人类的思想不是单线的,而是多线的,甚至是非线性。

你要把混乱而跳跃的思维,整理成单线结构,表达出来,让他人理解,谈何容易,通常都需要反复推敲和提炼。

举例来说,我们的思维可能是下图这样,好多点各自发散,连接在一起。

这种乱麻一团的思维并不可怕,可怕的是,你把文章也写成这样的结构,而不是耐心地梳理出一条线索。

科技动态

1、仓库机器人

亚马逊公司开始在仓库,测试一款人形机器人。

它用于捡货和搬运,每小时的运行成本是10至12美元。如果将来大量应用,成本可望降到2至3美元。

它跟工人一起工作(下图)。工人都非常害怕,这种机器人取代他们。亚马逊表示,机器人只是协助工人,并不会取代后者。

如果让你跟机器人一起上班,做差不多的事情,而且它还不要薪水,大概没人会心情好吧。

2、蜜蜂条形码

科学家研究蜜蜂,需要追踪每一只蜜蜂的行为,但怎样才能在一群蜜蜂中,分清谁是谁呢?

科学家想到了一个绝妙的办法,在每一只蜜蜂身上,贴上一个简化的二维码。

这种二维码的面积是2.1平方毫米(即边长不足1.5毫米),重0.6毫克,是工蜂重量的 0.7%,共可以表示2048只蜜蜂。

科学家手动为每只蜜蜂贴上二维码,一共贴了1400只,然后在高速摄像机下就可以读到这些二维码,从而分辨出每一只的行为。

蜂巢里面同时有上千只蜜蜂,放大图像后,就可以画出每只蜜蜂的行动路线(下图),分析它们在干什么,与谁合作。

3、舌头鼠标

今年的拉斯维加斯"消费电子展" CES 上,展示了一款"舌头鼠标"。

它使用牙套,将一块迷你触摸板固定在上颚,不需要用手,只用舌头就能控制鼠标。

这个设备的原意是,方便手部损伤的或瘫痪的人士使用电脑,但后来发现,它在健全人中也有市场,机械师或外科医生可以用它控制电脑,同时腾出双手干其他事情。

4、防盗盒

欧美的小型零售店,比如杂货店和小超市,越来越流行把商品放在防盗盒里面。

这种透明的塑料盒,需要钥匙才能打开,顾客自己取不出商品,只有店员才能打开。

盒子还内置 RFID 芯片,如果擅自带出商店,会引发警报器。这样就大大减少了商品损耗和被窃。

文章

1、高德地图如何实现红绿灯倒计时?(中文)

高德地图会显示,红绿灯倒计时读秒。本文介绍背后的专利。

2、2023年前端技术盘点与展望(中文)

腾讯云开发者公众号与腾讯 MoonWebTeam 前端团队联合推出的长篇技术报告。(@ryantang1991 投稿)

3、JS 空数组的 every() 方法(英文)

every() 方法对于空数组总是返回 true,这是为什么。

4、8个开源密码管理器介绍(英文)

密码管理器用来管理各种登录密码,本文介绍8个开源的密码管理器。

5、令人震惊的 CSS 动画效果(英文)

本文介绍一些高级的 CSS 动画技巧。

6、HTTP/3 详解(英文)

一组系列文章,向初学者介绍 HTTP/3 协议的设计,以及与 HTTP/2 的不同之处。

7、CPU 制造过程图解(英文)

作者使用大量图片,简明通俗解释如何从石头制造出 CPU。读了以后,对于 CPU 的制造流程就有一个大致的了解。

工具

1、Gemini Pro Chat

作者修改了 ChatGPT Next Web 的源码,使其可以用于 Gemini Pro,这里是 demo。(@lchh5 投稿)

2、WoodenFish

一个敲木鱼的网页 App,移动端打开时,只有侦测到手机陀螺仪的角度变化,才算一次敲击动作,这时可以把手机想象成敲木鱼的棒子。(@jwenjian 投稿)

3、Moodist

一个开源的 Docker 镜像文件,提供50多种背景声,比如风声、雨声、咖啡馆的声音。(@geekyouth 投稿)

4、Echo UI

一款专为 Web Audio API 设计的 UI 库,适合用来搭建基于 Web 的音频应用。(@codeacme17 投稿)

5、Photor

截图美化工具,可以在线使用,也可以通过浏览器插件使用。(@sleepy-zone 投稿)

6、Message Nest

开源的消息推送平台,整合邮件、钉钉、企业微信等多种通知方式。(@engigu 投稿)

7、Tiny RDM

Redis 桌面管理客户端,支持 Mac、Windows、Linux。(@tiny-craft 投稿)

8、Frigate

开源的摄像头固件,具有实时目标物体侦测。

9、InstantID

只使用一张图片,就可以提取人脸,用于个性化图像合成,并支持各种不同的风格,试用 Demo。(@zinc1234596 投稿)

10、HandBrake

一个跨平台的桌面应用,用于转换视频编码。

11、Animotion

一个网页 CSS 动画生成器,可视化设定动画,自动生成代码。

12、Ada

一个 URL 解析器,符合最新规范,使用 C++ 编写,可以快速处理 URL。

13、Inpaint-web

开源的图片修复和超分辨率工具, 纯浏览器端实现。(@lxfater 投稿)

14、人像生成工具

基于手绘风 SVG 人物画像集合 Open Peeps,一个人物画像的在线定制工具。(@zerosoul 投稿)

资源

1、唐库学习

电子书网站,提供世界名著的中英双语对照朗读。(@bigtang5 投稿)

2、AI 字体模型市场

该网站列出 AI 生成的字体,可以在线使用它们进行文字渲染。

它还支持网页手写八个字,生成自己的 AI 字体。(@qq345386817 投稿)

3、云原生应用市场

用户可以在这里浏览各种云原生应用,并一键安装到各类运行环境( Docker、Kubernetes、Rainbond),支持国内镜像加速。(@RainBondsongyg 投稿)

4、iHateRegex

一个收集常用正则表达式的资源库,并通过可视化帮助理解,基于 regexper。(@zkerhcy 投稿)

5、AsPoem.com

学习欣赏中国古诗词的网站。(@meetqy 投稿)

6、极简博客

作者用 NextJS + Laf 云搭建的博客托管网站,赠送二级域名。(@kingwrcy 投稿)

图片

1、旧金山人行道

下面是美国旧金山市的一段人行道,2015年的样子。

一位设计师决心改造这段人行道,营造出"城市森林"的景观。

人行道宽3.66米,他保留中间一半供通行,两侧改为绿化。

中间一段重新铺设路面以后,他在2016年在两侧种上植物。

2022年,这段路变成了下面这样。

这不由让人想起了那句有名的话:"种一棵树的最佳时间是十年前,其次就是现在。"

文摘

1、我装了一台 NetBSD 服务器

2010年的某一天,我接到一个电话。

客户想在内网部署几个服务(dhcp、内部 DNS、Apache + PHP 服务器、NFS 和 Samba 件服务器),需要架设一台服务器。

我建议客户购买企业级硬件,但是他们坚持使用已有的服务器,那是一台消费级电脑:没有双电源,没有远程管理功能,硬盘也是消费级的。

客户原计划安装 Windows 2008 Server,然后在上面部署这些服务。我考虑到只有两天时间,就建议改成安装 NetBSD 系统。客户同意了。

我安装完以后,就移交给了客户。后面的一个月,除了一些网络延迟问题,客户的反馈基本是正面的。

接下来的两三年里,我偶尔对这台服务器进行了一些调整,随后就与客户失去了联系。

2021年2月,我又接到了那个客户的电话,他们想要一个新的防火墙。这意味着那台 NetBSD 服务器还在运行!出于好奇,我接受了这个任务。

我惊讶地发现,这台服务器的工作完全正常。它不再对外网提供访问了,但在内网运行顺利。NFS SMB、DNS、SMTP 都是正常运行,它正在执行大约80%的原始任务。

最让我惊讶的是它的正常运行时间。上一次重启是在2012年,那时发生了一次小地震。客户有备用发电机,因此服务器始终拥有不间断电源。

谁能想到,这台机器当初只花了几个小时安装,而且全部都是消费级硬件,但是正常运行了九年没有重启,并且这些年基本上是无人管理的。

我现在明白了,为什么我没有----也永远不会----发财。我以前的老板抱怨,我偏爱为客户推荐稳定可靠的解决方案,这等于较少的长期利润。据他说,需要频繁维护的不可靠解决方案,才能带来最多的收入。但是我觉得,出色的工作应该是持续有效的,不需要不断的修复。

现在,我不确定这台服务器是否仍在运行,如果有机会我一定会检查一下。我很感激 NetBSD,它值得信赖,是一个轻量级、稳定、安全且高效的操作系统。在我看来,它至今仍然没有得到应有的赞誉和地位。

言论

1、

AI 聊天机器人很快就会变得强大无比,看上去像神一样,未来也许会出现崇拜 AI 的教派。

-- themessenger.com

2、

那些背负巨额债务以完成学业的学生,不太可能有远大的理想。因为当人们陷入债务时,他们就没有时间思考其他问题。

债务是一种改造手段,当这些学生毕业时,他们不仅背负着沉重的债务,思想上已经被改造过了,使他们成为消费经济的有效组成部分。

-- 诺姆·乔姆斯基,美国著名学者

3、

1931年,奥地利逻辑学家库尔特·哥德尔提出了重要的"哥德尔不完备定理"。他证明,任何一组数学公理都不可能是完备的,总有一些事实无法用这些公理来证明;同时,他还证明,没有一组公理具有一致性(即永远不会导致矛盾)。

这意味着,任何一个理论体系总有一些无法证明的命题,或者说,你能证明什么,取决于你的起始假设,而这些假设是不能证明的。

-- 《哥德尔不完备定理的证明》

4、

一家公司需要多少工程师?这与软件功能的数量有关,与软件用户的数量无关。

如果软件要添加更多功能,就需要更多工程师。如果软件功能单一,但是规模很大,甚至有几亿用户,事实上并不需要很多工程师。

-- Hacker News 读者

往年回顾

中国的增长动力在内陆(2023 #241)

一个程序员的财务独立之路(2022 #191)

封闭系统的胜利(2021 #141)

印度孟买的房价,为什么跟北京一样高?(2020 #91)

(完)

留言(42条)

我以前的老板抱怨,我偏爱为客户推荐稳定可靠的解决方案,这等于较少的长期利润。据他说,需要频繁维护的不可靠解决方案,才能带来最多的收入。

懂了

我是去年进公司当平台算法工程师的,当时需要搭一个k8s平台,然后上司就给了三台台式让我去搭了,总体来说遇到一些小问题,譬如主机性能不一致,在跑AI推理算法的时候,时不时会出现一下延时,其他的基本没什么问题;后面内存不够,又升级了一下内存,现在还在稳定运行中

> 如果软件要添加更多功能,就需要更多工程师。如果软件功能单一,但是规模很大,甚至有几亿用户,事实上并不需要很多工程师。

为几亿用户服务这件事本身就需要很多功能来实现,当然因为这是一项标准化的工作,现在可以交给云服务商解决,花点钱就行了

photor 这个,最早看到过英文实现(名字忘记了),没用过。今早上刚好有需要,就试用了 photor, 但是发现一个无解的问题:导出的图片分辨率降低了,里面的文字看起来有些模糊。

技术写作按照单一线性思维去写,人脑思维是网状的,要梳理出一条主线,不容易

技术写作学习了,继续深入实践当中,像榜样对齐。

iHateRegex
怕不是正则写烦了做出来的项目

感谢,又看到自己的作品被收录了 https://sinqi.tools/avatar

中国的人力成本是非常低的,平均每小时是12元

我现在明白了,为什么我没有----也永远不会----发财。我以前的老板抱怨,我偏爱为客户推荐稳定可靠的解决方案,这等于较少的长期利润。据他说,需要频繁维护的不可靠解决方案,才能带来最多的收入。
怪不得微软总喜欢在Windows上更新一些鸡肋的功能

对于中国的仓库工人:
好消息:3美元每小时的机器人成本和中国的人工成本相当。
坏消息:中国制造的机器人使用成本可能在每小时3元人民币。

只要克服了这个难点,就能继续往前走,不会有陷入迷宫、找不到方向、如坠五里雾中。
如坠五里雾中是不要改为云里雾中

咋啦?不太合常情呀!今天都这个点了,没见几个评论

NetBSD,职业操守与金钱利润,该如何去取舍?

这个舌头????鼠标简直就是ThinkPad小红点的完美平替,就是带着工作感觉会比较怪。

红绿灯那个楞是没看懂,我一直以为是接入交通局之类的系统里的。这还能通过大数据计算出来?

追踪蜜蜂的话,是不是也可以选择小型雷达

那个商品防盗盒真的是直观的演示了什么叫做社会运行成本

兄弟们,开摸,周末愉快!

引用Donne的发言:

红绿灯那个楞是没看懂,我一直以为是接入交通局之类的系统里的。这还能通过大数据计算出来?

红绿灯的等待时间是固定的,很大程度上降低了预测难度。

其实加州很缺水的,在加州搞城市森林景观算是逆天而行了

原来高德地图的红绿灯倒计时是这样实现的,感觉很不安全,万一正好那个路口的的红绿灯时间间隔调整了,这种算法不能及时更新,岂不容易出问题

引用Donne的发言:

红绿灯那个楞是没看懂,我一直以为是接入交通局之类的系统里的。这还能通过大数据计算出来?

两种都有。交通局有提供即时数据的,用交通局的。没有的,就自已算。

写清楚就行,有条理,画画流程图,言简意赅,没有难度,

看到去年的文章标题:中国的增长动力在内陆(2023 #241)
回看2023年,年初时大家还抱着解封后经济反弹的信心,但最终走来还是不尽如人意,内陆各省地方债问题比较严重,大家看不到未来收入增长的预期,储蓄率升高,消费低迷,一言难尽...

偶尔点开了看看,这个网页可真是宝藏

古诗词那个网站内容很少

引用matt的发言:

原来高德地图的红绿灯倒计时是这样实现的,感觉很不安全,万一正好那个路口的的红绿灯时间间隔调整了,这种算法不能及时更新,岂不容易出问题

算法里应该有兼容的代码,固定间隔时间执行一次推算红绿灯时间间隔,另外驾驶员也不可能完全只看导航里的红绿灯倒计时,只作为一个参考,现实肯定还是以人眼看到的红绿灯倒计时为准,路口慢行是老司机的基本驾驶意识(:dog)

机器人的确不用工资,但不是免费的。使用者需要支付运维费用以及升级费用,不用的话还要报废。如果这些总费用加起来低于人工的话,资本家早就换了。之所以现在还不替代,不是因为怜悯而纯粹是费用上的考量。

红绿灯的问题我原本以为是联网数据,好厉害的发明,学到了

微信读书的特定版本(7.3.7)也支持中英双语朗读,只要导入英文书籍,使用听书功能就会先朗读一遍英文再朗读一遍中文。
新版本已经把这个功能去掉了,需要安装特定版本。

引用hikingman的发言:

回看2023年,年初时大家还抱着解封后经济反弹的信心,但最终走来还是不尽如人意,内陆各省地方债问题比较严重,大家看不到未来收入增长的预期,储蓄率升高,消费低迷,一言难尽...

不说增长了,看到的是收入下降的预期。

引用sruby的发言:

不说增长了,看到的是收入下降的预期。

目前看来全世界都是这样,没有幸免,熬下去吧放弃非必要支出

引用Donne的发言:

红绿灯那个楞是没看懂,我一直以为是接入交通局之类的系统里的。这还能通过大数据计算出来?

调用以往车辆经过这个路口什么时候停下来又经过多长时间走,然后靠这种大量的数据计算出来。

引用Donne的发言:

红绿灯那个楞是没看懂,我一直以为是接入交通局之类的系统里的。这还能通过大数据计算出来?

一开始就感觉还是大数据做的,因为有一段时间我使用的时候红灯总会比实际的块几秒,猜测是大家在这些路口起步的比较早。

“我现在明白了,为什么我没有----也永远不会----发财。我以前的老板抱怨,我偏爱为客户推荐稳定可靠的解决方案,这等于较少的长期利润。据他说,需要频繁维护的不可靠解决方案,才能带来最多的收入”

这种价值观不会被消费者追随,终会被抛弃。更好的价值观应该是推荐稳定可靠的解决方案,到达顶尖,再发展创新其他领域,往外拓展来解决如何发财的问题。

言论2的超链接不对

上周去颐和园滑冰,结果手机丢了,应该被人捡到了,但是估计不想归还,一直关机和开飞行模式,最后连续三天的定位都在颐和园。再也不想去颐和园了,伤心~~~

「哥德爾不完備定理」是說任何足夠複雜的公理系統都不可以同時是完備或一致性

完備是指可以証明任何用該公理系統語言編寫的東西

一致性是指沒有內部矛盾

數學的公理系統必須是一致性,所以必然不完備

WOW,新年第一帖,满满的干货!关于技术写作,也许金字塔原理更实用。

NetBSD那个,和防御性编程有异曲同工之妙

技术写作 的内容受教了。不论是写作、PPT还是程序设计,要围绕着某个线索,梳理成单线结构

我要发表看法

«-必填

«-必填,不公开

«-我信任你,不会填写广告链接