405 lines
20 KiB
Markdown
405 lines
20 KiB
Markdown
# 科技爱好者周刊（第 288 期）：技术写作的首要诀窍
|
||
|
||
这里记录每周值得分享的科技内容，周五发布。
|
||
|
||
本杂志[开源](https://github.com/ruanyf/weekly)，欢迎[投稿](https://github.com/ruanyf/weekly/issues)。另有[《谁在招人》](https://github.com/ruanyf/weekly/issues/3814)服务，发布程序员招聘信息。合作请[邮件联系](mailto:yifeng.ruan@gmail.com)（yifeng.ruan@gmail.com）。
|
||
|
||
## 封面图
|
||
|
||
|
||
|
||
在昔日的“皇家园林”北京颐和园，昆明湖已经完全结冰，变成了游人玩乐的大冰场。夕阳西下，湖上的十七孔桥现出了“金光穿洞”景观。（[via](https://news.66wz.com/system/2024/01/15/105618610.shtml)）
|
||
|
||
## 技术写作的首要诀窍
|
||
|
||
技术写作非常重要，产品的开发、推广、维护都需要它。
|
||
|
||
|
||
|
||
跟大家想的不一样，**技术写作的好坏，跟语文水平关系不大，更多是一个技巧问题**。
|
||
|
||
因为技术写作的评价标准，不是艺术性，而是表达是否清楚明白。它不需要华丽的词藻、巧妙的比喻、深刻的感悟，只需要把问题说清楚。
|
||
|
||
**把问题说清楚的关键，在于你的思想是否清楚。**
|
||
|
||
|
||
|
||
当你想清楚了一个问题，只要掌握几个基本诀窍，就能写出一篇很好的技术文章。
|
||
|
||
今天，我来说说，技术写作的首要诀窍是什么。很简单，就是一句话：**文章采用单线结构**。
|
||
|
||
所谓“单线结构”（也称“线性结构”），指的是一篇文章只说一件事，按照线性顺序进行叙述，由浅入深、循序渐进、平铺直叙、层层递进。
|
||
|
||
这就好比一个游览区，只有一条游览路线，从入口到出口，跟着箭头一路走，就能看到所有景观，非常明白清楚。
|
||
|
||
如果同时有好几条路线，游客就会糊涂，到底选哪一条？会不会错过景观？要是这些路线还互相交叉，那就更糟糕了，游客非串线不可。
|
||
|
||
|
||
|
||
（图片说明：上面的景区路线图，应该选择哪条路线吗？）
|
||
|
||
只要采用了单线结构，技术文章就不会太差。即使内容是难懂的，至少结构是清晰的，一环扣一环，读者能知道自己卡在哪一环上。只要克服了这个难点，就能继续往前走，不会有陷入迷宫、找不到方向、如坠五里雾中。
|
||
|
||
有一篇[老外的文章](https://thisisimportant.net/posts/content-as-a-graph/)，使用图形表示文章结构，非常形象。
|
||
|
||
|
||
|
||
上图就是单线结构，按照箭头，一步步推进。
|
||
|
||
有的问题比较复杂，涉及多个因素，可能是星状结构。
|
||
|
||
|
||
|
||
也可能是”层次结构”。
|
||
|
||
|
||
|
||
这时，建议把这个问题拆分成多篇文章，每篇文章保持单线结构，坚持做到一篇文章只讲一点，而且争取把这一点讲透。
|
||
|
||
但是，单线结构说起来容易，做起来难。难就难在，人类的思想不是单线的，而是多线的，甚至是非线性。
|
||
|
||
你要把混乱而跳跃的思维，整理成单线结构，表达出来，让他人理解，谈何容易，通常都需要反复推敲和提炼。
|
||
|
||
举例来说，我们的思维可能是下图这样，好多点各自发散，连接在一起。
|
||
|
||
|
||
|
||
|
||
|
||
这种乱麻一团的思维并不可怕，可怕的是，你把文章也写成这样的结构，而不是耐心地梳理出一条线索。
|
||
|
||
## 科技动态
|
||
|
||
1、[仓库机器人](https://www.businessinsider.com/new-amazon-warehouse-robot-humanoid-2023-10)
|
||
|
||
亚马逊公司开始在仓库，测试一款人形机器人。
|
||
|
||
|
||
|
||
它用于捡货和搬运，每小时的运行成本是10至12美元。如果将来大量应用，成本可望降到2至3美元。
|
||
|
||
|
||
|
||
它跟工人一起工作（下图）。工人都非常害怕，这种机器人取代他们。亚马逊表示，机器人只是协助工人，并不会取代后者。
|
||
|
||
|
||
|
||
如果让你跟机器人一起上班，做差不多的事情，而且它还不要薪水，大概没人会心情好吧。
|
||
|
||
2、[蜜蜂条形码](https://theapiarist.org/barcoding-bees/)
|
||
|
||
科学家研究蜜蜂，需要追踪每一只蜜蜂的行为，但怎样才能在一群蜜蜂中，分清谁是谁呢？
|
||
|
||
科学家想到了一个绝妙的办法，在每一只蜜蜂身上，贴上一个简化的二维码。
|
||
|
||
|
||
|
||
这种二维码的面积是2.1平方毫米（即边长不足1.5毫米），重0.6毫克，是工蜂重量的 0.7%，共可以表示2048只蜜蜂。
|
||
|
||
科学家手动为每只蜜蜂贴上二维码，一共贴了1400只，然后在高速摄像机下就可以读到这些二维码，从而分辨出每一只的行为。
|
||
|
||
|
||
|
||
|
||
|
||
蜂巢里面同时有上千只蜜蜂，放大图像后，就可以画出每只蜜蜂的行动路线（下图），分析它们在干什么，与谁合作。
|
||
|
||
|
||
|
||
3、[舌头鼠标](https://www.nbcnews.com/tech/tech-news/tongue-controlled-touchscreens-hit-market-year-rcna133270)
|
||
|
||
今年的拉斯维加斯“消费电子展” CES 上，展示了一款“舌头鼠标”。
|
||
|
||
|
||
|
||
它使用牙套，将一块迷你触摸板固定在上颚，不需要用手，只用舌头就能控制鼠标。
|
||
|
||
这个设备的原意是，方便手部损伤的或瘫痪的人士使用电脑，但后来发现，它在健全人中也有市场，机械师或外科医生可以用它控制电脑，同时腾出双手干其他事情。
|
||
|
||
4、[防盗盒](https://www.curbed.com/2023/01/shoplifting-crime-wave-spam-keeper-retail-loss-prevention-design.html)
|
||
|
||
欧美的小型零售店，比如杂货店和小超市，越来越流行把商品放在防盗盒里面。
|
||
|
||
|
||
|
||
这种透明的塑料盒，需要钥匙才能打开，顾客自己取不出商品，只有店员才能打开。
|
||
|
||
|
||
|
||
盒子还内置 RFID 芯片，如果擅自带出商店，会引发警报器。这样就大大减少了商品损耗和被窃。
|
||
|
||
|
||
|
||
## 文章
|
||
|
||
1、[高德地图如何实现红绿灯倒计时？](https://mp.weixin.qq.com/s/3_LNM62zoHaJsmvAryujEw)（中文）
|
||
|
||
|
||
|
||
高德地图会显示，红绿灯倒计时读秒。本文介绍背后的专利。
|
||
|
||
2、[2023年前端技术盘点与展望](https://mp.weixin.qq.com/s/LiygBJqMN8U_vSpAjxMibQ)（中文）
|
||
|
||
腾讯云开发者公众号与腾讯 MoonWebTeam 前端团队联合推出的长篇技术报告。（[@ryantang1991](https://github.com/ruanyf/weekly/issues/3917) 投稿）
|
||
|
||
3、[JS 空数组的 every() 方法](https://humanwhocodes.com/blog/2023/09/javascript-wtf-why-does-every-return-true-for-empty-array/)（英文）
|
||
|
||
|
||
|
||
every() 方法对于空数组总是返回 true，这是为什么。
|
||
|
||
4、[8个开源密码管理器介绍](https://itsfoss.com/open-source-password-managers/)（英文）
|
||
|
||
|
||
|
||
密码管理器用来管理各种登录密码，本文介绍8个开源的密码管理器。
|
||
|
||
5、[令人震惊的 CSS 动画效果](https://codersblock.com/blog/the-surprising-things-that-css-can-animate/)（英文）
|
||
|
||
|
||
|
||
本文介绍一些高级的 CSS 动画技巧。
|
||
|
||
6、[HTTP/3 详解](https://www.smashingmagazine.com/2021/08/http3-core-concepts-part1/)（英文）
|
||
|
||
|
||
|
||
一组系列文章，向初学者介绍 HTTP/3 协议的设计，以及与 HTTP/2 的不同之处。
|
||
|
||
7、[CPU 制造过程图解](https://blog.robertelder.org/how-to-make-a-cpu/)（英文）
|
||
|
||
|
||
|
||
作者使用大量图片，简明通俗解释如何从石头制造出 CPU。读了以后，对于 CPU 的制造流程就有一个大致的了解。
|
||
|
||
## 工具
|
||
|
||
1、[Gemini Pro Chat](https://github.com/lchh5/GeminiPro-Next-Web)
|
||
|
||
|
||
|
||
作者修改了 ChatGPT Next Web 的源码，使其可以用于 Gemini Pro，这里是 [demo](https://chat.googlegemini.co/)。（[@lchh5](https://github.com/ruanyf/weekly/issues/3923) 投稿）
|
||
|
||
2、[WoodenFish](https://github.com/jwenjian/wooden-fish)
|
||
|
||
|
||
|
||
一个敲木鱼的网页 App，移动端打开时，只有侦测到手机陀螺仪的角度变化，才算一次敲击动作，这时可以把手机想象成敲木鱼的棒子。（[@jwenjian](https://github.com/ruanyf/weekly/issues/3929) 投稿）
|
||
|
||
3、[Moodist](https://github.com/geekyouth/moodist)
|
||
|
||
|
||
|
||
一个开源的 Docker 镜像文件，提供50多种[背景声](https://moodist.java666.cn/)，比如风声、雨声、咖啡馆的声音。（[@geekyouth](https://github.com/ruanyf/weekly/issues/3943) 投稿）
|
||
|
||
4、[Echo UI](https://echoui.dev/zh/)
|
||
|
||
|
||
|
||
一款专为 Web Audio API 设计的 UI 库，适合用来搭建基于 Web 的音频应用。（[@codeacme17](https://github.com/ruanyf/weekly/issues/3946) 投稿）
|
||
|
||
5、[Photor](https://www.photor.fun/)
|
||
|
||
|
||
|
||
截图美化工具，可以在线使用，也可以通过浏览器插件使用。（[@sleepy-zone](https://github.com/ruanyf/weekly/issues/3948) 投稿）
|
||
|
||
6、[Message Nest](https://github.com/engigu/Message-Push-Nest)
|
||
|
||
|
||
|
||
开源的消息推送平台，整合邮件、钉钉、企业微信等多种通知方式。（[@engigu](https://github.com/ruanyf/weekly/issues/3947) 投稿）
|
||
|
||
7、[Tiny RDM](https://redis.tinycraft.cc/zh/)
|
||
|
||
|
||
|
||
Redis 桌面管理客户端，支持 Mac、Windows、Linux。（[@tiny-craft](https://github.com/ruanyf/weekly/issues/3955) 投稿）
|
||
|
||
8、[Frigate](https://github.com/blakeblackshear/frigate)
|
||
|
||
|
||
|
||
开源的摄像头固件，具有实时目标物体侦测。
|
||
|
||
9、[InstantID](https://github.com/InstantID/InstantID)
|
||
|
||
|
||
|
||
只使用一张图片，就可以提取人脸，用于个性化图像合成，并支持各种不同的风格，试用 [Demo](https://instantid.org/#playground)。（[@zinc1234596](https://github.com/ruanyf/weekly/issues/3959) 投稿）
|
||
|
||
10、[HandBrake](https://handbrake.fr/)
|
||
|
||
|
||
|
||
一个跨平台的桌面应用，用于转换视频编码。
|
||
|
||
11、[Animotion](https://cssanimotion.pages.dev/)
|
||
|
||
|
||
|
||
一个网页 CSS 动画生成器，可视化设定动画，自动生成代码。
|
||
|
||
12、[Ada](https://github.com/ada-url/ada)
|
||
|
||
|
||
|
||
一个 URL 解析器，符合最新规范，使用 C++ 编写，可以快速处理 URL。
|
||
|
||
13、[Inpaint-web](https://github.com/lxfater/inpaint-web)
|
||
|
||
|
||
|
||
开源的图片修复和超分辨率工具, 纯浏览器端实现。（[@lxfater](https://github.com/ruanyf/weekly/issues/3964) 投稿）
|
||
|
||
14、[人像生成工具](https://sinqi.tools/zh/avatar)
|
||
|
||
|
||
|
||
基于手绘风 SVG 人物画像集合 [Open Peeps](https://www.openpeeps.com/)，一个人物画像的在线定制工具。（[@zerosoul](https://github.com/ruanyf/weekly/issues/3968) 投稿）
|
||
|
||
## 资源
|
||
|
||
1、[唐库学习](http://www.tanglib.com/)
|
||
|
||
|
||
|
||
电子书网站，提供世界名著的中英双语对照朗读。（[@bigtang5](https://github.com/ruanyf/weekly/issues/3918) 投稿）
|
||
|
||
2、[AI 字体模型市场](https://www.ai.zitijia.com/list/1)
|
||
|
||
|
||
|
||
该网站列出 AI 生成的字体，可以在线使用它们进行文字渲染。
|
||
|
||
|
||
|
||
它还支持网页手写八个字，生成自己的 AI 字体。（[@qq345386817](https://github.com/ruanyf/weekly/issues/3930) 投稿）
|
||
|
||
3、[云原生应用市场](https://hub.grapps.cn/)
|
||
|
||
|
||
|
||
用户可以在这里浏览各种云原生应用，并一键安装到各类运行环境（ Docker、Kubernetes、Rainbond），支持国内镜像加速。（[@RainBondsongyg](https://github.com/ruanyf/weekly/issues/3956) 投稿）
|
||
|
||
4、[iHateRegex](https://ihateregex.io/)
|
||
|
||
|
||
|
||
一个收集常用正则表达式的资源库，并通过可视化帮助理解，基于 [regexper](https://github.com/ruanyf/weekly/issues/regexper.com)。（[@zkerhcy](https://github.com/ruanyf/weekly/issues/3938) 投稿）
|
||
|
||
5、[AsPoem.com](https://aspoem.com/)
|
||
|
||
|
||
|
||
学习欣赏中国古诗词的网站。（[@meetqy](https://github.com/ruanyf/weekly/issues/3941) 投稿）
|
||
|
||
6、[极简博客](https://dev.mblog.club/)
|
||
|
||
|
||
|
||
作者用 NextJS + Laf 云搭建的博客托管网站，赠送二级域名。（[@kingwrcy](https://github.com/ruanyf/weekly/issues/3922) 投稿）
|
||
|
||
## 图片
|
||
|
||
1、[旧金山人行道](https://zachklein.com/Sidewalk+Garden)
|
||
|
||
下面是美国旧金山市的一段人行道，2015年的样子。
|
||
|
||
|
||
|
||
一位设计师决心改造这段人行道，营造出“城市森林”的景观。
|
||
|
||
人行道宽3.66米，他保留中间一半供通行，两侧改为绿化。
|
||
|
||
|
||
|
||
中间一段重新铺设路面以后，他在2016年在两侧种上植物。
|
||
|
||
|
||
|
||
|
||
|
||
2022年，这段路变成了下面这样。
|
||
|
||
|
||
|
||
|
||
|
||
这不由让人想起了那句有名的话：“种一棵树的最佳时间是十年前，其次就是现在。”
|
||
|
||
## 文摘
|
||
|
||
1、[我装了一台 NetBSD 服务器](https://it-notes.dragas.net/2023/08/27/that-old-netbsd-server-running-since-2010/)
|
||
|
||
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](https://themessenger.com/tech/church-artificial-intelligence-worship-god)
|
||
|
||
2、
|
||
|
||
那些背负巨额债务以完成学业的学生，不太可能有远大的理想。因为当人们陷入债务时，他们就没有时间思考其他问题。
|
||
|
||
债务是一种改造手段，当这些学生毕业时，他们不仅背负着沉重的债务，思想上已经被改造过了，使他们成为消费经济的有效组成部分。
|
||
|
||
-- [诺姆·乔姆斯基](https://medium.com/blob-streaming/programming-as-a-career-isnt-right-for-me-f9f0846fef82)，美国著名学者
|
||
|
||
3、
|
||
|
||
1931年，奥地利逻辑学家库尔特·哥德尔提出了重要的“哥德尔不完备定理”。他证明，任何一组数学公理都不可能是完备的，总有一些事实无法用这些公理来证明；同时，他还证明，没有一组公理具有一致性（即永远不会导致矛盾）。
|
||
|
||
这意味着，任何一个理论体系总有一些无法证明的命题，或者说，你能证明什么，取决于你的起始假设，而这些假设是不能证明的。
|
||
|
||
-- [《哥德尔不完备定理的证明》](https://www.quantamagazine.org/how-godels-proof-works-20200714/)
|
||
|
||
4、
|
||
|
||
一家公司需要多少工程师？这与软件功能的数量有关，与软件用户的数量无关。
|
||
|
||
如果软件要添加更多功能，就需要更多工程师。如果软件功能单一，但是规模很大，甚至有几亿用户，事实上并不需要很多工程师。
|
||
|
||
-- [Hacker News 读者](https://news.ycombinator.com/item?id=34567237)
|
||
|
||
## 往年回顾
|
||
|
||
[中国的增长动力在内陆](https://www.ruanyifeng.com/blog/2023/02/weekly-issue-241.html)（2023 #241）
|
||
|
||
[一个程序员的财务独立之路](https://www.ruanyifeng.com/blog/2022/01/weekly-issue-191.html)（2022 #191）
|
||
|
||
[封闭系统的胜利](https://www.ruanyifeng.com/blog/2021/01/weekly-issue-141.html)（2021 #141）
|
||
|
||
[印度孟买的房价，为什么跟北京一样高？](https://www.ruanyifeng.com/blog/2020/01/weekly-issue-91.html)（2020 #91）
|
||
|
||
（完）
|
||
|