科技愛好者週刊(第 288 期):技術寫作的首要訣竅

阮一峰發表於2024-01-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)

(完)

相關文章