背景#
最近在思考這個問題，如何讓技術文檔做得更好？
最近有兩件事情促使我開始思考：
- 看到了 ViteConf 上 Sarah Rainsberger 分享的《Stop writing docs; Start helping》視頻
- 最近 sync-to-xlog 插件的一個文檔 PR
逐一做個解釋。
文檔是用來幫助人的#
Sarah Rainsberger 是 Astro 的文檔主管，這是她在 ViteConf2023 上的演講。我做了視頻搬運，可以在 B 站觀看 # Astro 文檔負責人分享什麼是好的技術文檔，如何改進
內部鏈接： [[stop writing docs start helping]]
舉了一個非常經典的例子：
溯源 來源
上圖內容是，介紹安裝的方案。這個例子有點中人心，原來的技術文檔非常好，能激勵讀者、解釋作者的想法。改進後只需要一句話，幾個單詞。
在此時此刻，讀者需要的幫助是告訴他如何進行安裝，清晰、明確地告訴讀者就好了。
文檔的 PR#
我的想法：
- 勇敢使用 H1
- 如何安裝，要區分前置。該截圖改加註釋，標紅加箭頭，不犯法
- 減少口水話，更中立、忠實、平靜地描述事實
- 還得多看多寫
文檔可以從無到有，從有到優。
後面編寫文檔時刻留意，爭取做得更好。
我看提到的那個文檔大一統理論挺好，或許可以翻譯。