技術寫作的相關重點

本文整理技術寫作相關知識，還在很草稿的階段，因為我自己的知識也還不足以真正介紹這個主題。

越寫越多的心得是，人類的關注度是非常低落的，幾乎所有注意事項都是以關注度低落為前提創造出來的。

  1. 人的認知有限，不可以放太多內容，文章需遵守 7+-2 法則
  2. 放 TL;DR，重要的要先講，放到後面不只人類會跳過，AI 也會跳過
  3. 避免 context-switching，人類的切換不只是延遲，而是記憶斷層和關注度流失
  4. 因此才要 self-contained，除非必要，不要將內容拆成兩份（網頁）說明
  5. 最小化連結，最好是不要有任何連結
  6. 最小化表達，只有非常重要才寫，次要重要、不是很重要的一概不寫
  7. 句子短，每個段落不要超過五句話
  8. 技術寫作不是一般文章寫作，不需要上下文連接用語
  9. 如果有選項，明確告訴用戶怎麼選
  10. 語氣明確、權威、主動式（英文），不要創造任何懷疑空間
  11. 用字遣辭明確，就如同 coding 的 variable naming 一樣，不是 cache，而是 xxx_cache，用字不可產生歧義

至於要怎麼讓句子精確簡短，具體是微軟說的 bigger idea, fewer words，不該發生字很多的情況，如果一個概念要花很多字才能講清楚，那就代表作者筆力太差、作者自己也不是很理解，尤其是軟體工具更不會發生這種問題。

正面例子

負面例子

不想講了，某四個字的 CLI 軟體在 Getting Started 教學裡面給了 19 個連結，天才一個。

閱讀

我還沒讀，先放著。

  • 結構化寫作-讓表達快、准、好的秘密
#文檔撰寫 #筆記