Vue 3.0文檔編寫指南

譯者：本章節(jié)大部分內容是針對母語是英文的讀者，中文用戶可略讀，除非你想以英文文檔編寫者的身份參與 Vue docs 的編寫，

編寫文檔是一種換位思考的練習。我們并不是在描述客觀現(xiàn)實——源代碼已經(jīng)做到了。我們的工作是幫助塑造用戶與 Vue 生態(tài)系統(tǒng)之間的關系。這份不斷發(fā)展的指南提供了一些規(guī)則和建議，說明如何在 Vue 生態(tài)系統(tǒng)中始終如一地做到這一點。

#原則

• 除非有充分的文檔證明，否則功能不存在。
• 尊重用戶的認知能力 (即腦力)。當用戶開始閱讀時，他們從一定量的有限腦力開始，而當他們用完時，他們停止學習。
  • 復雜的句子、一次必須學習一個以上的概念，以及與用戶的工作沒有直接關系的抽象例子，認知能力消耗得更快。
  • 當我們幫助他們持續(xù)感到聰明、強大和好奇時，他們的認知能力會慢慢消耗殆盡。把事情分解成可消化的部分并注意文檔的流動可以幫助它們保持這種狀態(tài)。
• 總是試著從用戶的角度看問題。當我們徹底理解某件事情時，它就變得顯而易見了。這就是所謂的知識詛咒。為了編寫好的文檔，記住在學習這個概念時首先需要知道什么。你需要學什么行話？你誤解了什么？什么花了很長時間才真正掌握？好的文檔可以滿足用戶的需求。這可能有助于練習向人們解釋這個概念
• 首先描述*問題*，然后描述解決方案。在展示功能如何工作之前，解釋其存在的原因非常重要。否則，用戶將無法知道這些信息對他們是否重要 (這是他們遇到的問題嗎？) 或與之前的知識/經(jīng)驗相聯(lián)系。
• 在寫作時，不要害怕問問題，尤其是如果你害怕他們“蠢”的話。脆弱是很難的，但這是我們更充分地理解我們需要解釋的唯一途徑。
• 參與特性討論。最好的 API 來自于文檔驅動的開發(fā)，我們在開發(fā)中構建易于解釋的特性，而不是試圖在以后解釋它們。提前提出問題 (尤其是“愚蠢的”問題) 通常有助于揭示困惑、不一致和有問題的行為，然后才需要進行破壞性的更改來修復它們。

#組織

• 安裝/集成：提供有關如何將軟件集成到盡可能多的不同項目中的全面概述。
• 介紹/起步：
  • 提供一個不到 10 分鐘的項目解決的問題及其存在原因的概述。
  • 提供一個不到 30 分鐘的項目解決的問題和如何解決的概述，包括何時和為什么使用項目以及一些簡單的代碼示例。最后，鏈接到安裝頁面和要點指南的開頭。
• 指南：讓用戶感到聰明、強大、好奇，然后保持這種狀態(tài)，讓用戶保持不斷學習的動力和認知能力。指南頁是按順序閱讀的，因此通常應該從最高到最低的功率/工作比排序。
  • 要點：閱讀要領的時間不應超過 5 個小時，但越短越好。它的目標是提供 20%的知識來幫助用戶處理 80%的用例。Essentials 可以鏈接到更高階的指南和 API，不過，在大多數(shù)情況下，你應該避免此類鏈接。當它們被提供時，你還需要提供一個上下文，以便用戶知道他們是否應該在第一次閱讀時遵循這個鏈接。否則，許多用戶最終會耗盡他們的認知能力，跳轉鏈接，試圖在繼續(xù)之前全面了解一個功能的各個方面，結果是，永遠無法完成第一次通讀的要領。記住，通順的閱讀比徹底的閱讀更重要。我們想給人們提供他們需要的信息，以避免令人沮喪的經(jīng)歷，但他們總是可以回來繼續(xù)閱讀，或者在谷歌遇到一個不太常見的問題。
  • 高階：雖然要點幫助人們處理大約 80%的用例，但后續(xù)的指南幫助用戶了解 95%的用例，以及關于非基本特性 (例如轉換、動畫)、更復雜的便利特性 (例如 mixin、自定義指令) 和開發(fā)人員體驗改進 (例如 JSX、插件) 的更詳細信息。最后 5%的用例是更利基的、更復雜的和/或更容易被濫用的，將留給烹飪書和 API 參考，它們可以從這些高階指南鏈接到。
• 引用/API：提供功能的完整列表，包括類型信息，每個要解決的問題的描述，選項的每種組合的示例以及指向指南，食譜的食譜以及提供更多詳細信息的其他內部資源的鏈接。與其他頁面不同，此頁面無意自上而下閱讀，因此可以提供大量詳細信息。這些參考資料還必須比指南更容易瀏覽，因此格式應比指南的講故事格式更接近字典條目。
• 遷移：
  • 版本：當進行了重要的更改時，包含一個完整的更改列表是很有用的，包括對為什么進行更改以及如何遷移其項目的詳細解釋。
  • 從其他項目：這個軟件與同類軟件相比如何？這對于幫助用戶了解我們可能為他們解決或創(chuàng)造的其他問題，以及他們可以在多大程度上轉移他們已經(jīng)擁有的知識，這一點很重要。
• 風格指南：開發(fā)中必然有一些關鍵部分需要決策，但它們不是 API 的核心。風格指南提供了受過教育的、有主見的建議，以幫助指導這些決策。他們不應該盲目遵循，但可以幫助團隊節(jié)省時間，在較小的細節(jié)上保持一致。
• Cookbook：Cookbook 中的秘訣是基于對 Vue 及其生態(tài)系統(tǒng)的熟悉程度而編寫的。每一個文檔都是一個高度結構化的文檔，它詳細介紹了 Vue 開發(fā)人員可能遇到的一些常見實現(xiàn)細節(jié)。

#寫作 & 語法

#風格

• 標題應該描述問題，不是解決方案。例如，一個不太有效的標題可能是“使用 prop”，因為它描述了一個解決方案。一個更好的標題可能是“通過 Props 將數(shù)據(jù)傳遞給子組件”，因為它提供了 Props 解決問題的上下文。用戶不會真正開始注意某個功能的解釋，直到他們知道為什么/何時使用它。
• 當你假設知識時，就要聲明它，在開始時，鏈接到參考資料，以獲得你期望的不太常見的知識。
• 盡可能一次只引入一個新概念 (包括文本和代碼示例)，即使當你介紹不止一個的時候很多人都能理解，也有很多人會迷失方向，即使那些沒有迷失方向的人也會耗盡更多的認知能力。
• 盡可能避免使用特殊的內容塊來獲取提示和注意事項，一般來說，最好將這些內容更自然地融合到主要內容中，例如，通過構建示例來演示邊緣案例。
• 每頁不要超過兩個相互交織的提示和注意事項，如果你發(fā)現(xiàn)一個頁面需要兩個以上的提示，請考慮添加一個警告部分來解決這些問題。本指南的目的是通讀，提示和注意事項可能會讓試圖理解基本概念的人不知所措或分心。
• 避免訴諸權威 (例如，“你應該做 X，因為這是一個最佳實踐”或“X 是最好的，因為它能讓你完全分離關注點”)。相反，用例子來演示由模式引起和/或解決的具體人類問題。
• 當決定先教什么時，想想哪些知識能提供最好的動力/努力比。這意味著教任何能幫助用戶解決最大痛苦或最大數(shù)量問題的東西，而學習的努力相對較少。這有助于學習者感到聰明、強大和好奇，因此他們的認知能力會慢慢流失。
• 除非上下文采用字符串模板或構建系統(tǒng)，否則只能編寫在軟件的任何環(huán)境中工作的代碼 (例如 Vue、Vuex 等)
• 顯示，不要說例如，“要在頁面上使用 Vue，可以將其添加到 HTML 中”(然后顯示腳本標記)，而不是“要在頁面上使用 Vue，可以添加一個具有 src 屬性的腳本元素，該屬性的值應為指向 Vue 編譯源的鏈接”。
• 幾乎總是避免幽默 (對于英文文檔)， 尤其是諷刺和通俗文化的引用，因為它在不同文化之間的翻譯并不好。
• 永遠不要假設比你必須的更高階的上下文。
• 在大多數(shù)情況下，比起在多個部分中重復相同的內容，更喜歡在文檔的各個部分之間建立鏈接。在內容上有些重復是不可避免的，甚至是學習的必要條件。然而，過多的重復也會使文檔更難維護，因為 API 的更改將需要在許多地方進行更改，而且很容易遺漏某些內容。這是一個很難達到的平衡。
• 具體的比一般的好例如，一個 <BlogPost> 組件例子比 <ComponentA> 更好。
• 相對勝于晦澀。例如，一個 <BlogPost> 組件例子比 <CurrencyExchangeSettings> 更好。
• 保持情感相關。與人們有經(jīng)驗并關心的事物相關的解釋和示例將永遠更加有效。
• 始終喜歡使用簡單，簡單的語言，而不是復雜或專業(yè)的語言。例如：
  • “你可以將 Vue 與腳本元素一起使用”，而不是“為了啟動 Vue 的使用，一種可能的選擇是通過腳本 HTML 元素實際注入它”
  • “返回函數(shù)的函數(shù)”而不是“高階函數(shù)”
• 避免使用毫無意義的語言。如“簡單”、“公正”、“明顯”等，請參閱教育寫作中應避免的詞語。

#語法

• 避免縮寫在編寫代碼和示例代碼中 (例如，attribute 優(yōu)于 attr，message 優(yōu)于 msg)，除非你在 API 中明確引用了縮寫 (例如 $attrs)。標準鍵盤上包含的縮寫符號 (例如，@，#，&) 可以。
• 當引用直接下面的示例時，請使用冒號 (:) 結束句子，而不是句點 (.)
• 使用牛津逗號 (；例如：“a，b，and c”替換“a，b and c”)。！為什么牛津逗號很重要
  • 來源：The Serial (Oxford) Comma：When and Why To Use It
• 引用項目名稱時，請使用項目引用自身的名稱。例如，“webpack”和“npm”都應使用小寫字母，因為這是它們的文檔引用它們的方式。
• 使用標題大小寫作為標題 - 至少到目前為止，因為這是我們在其余文檔中使用的。有研究表明，句子大小寫 (僅標題的第一個單詞以大寫字母開頭) 實際上在可讀性上是優(yōu)越的，并且還減少了文檔作者的認知開銷，因為他們不必記住是否要大寫“and”，“with”和“about”。
• 請勿使用表情符號 (討論中除外)。Emoji 既可愛又友好，但是它們可能會使文檔分散注意力，有些表情符號甚至會在不同文化中傳達不同的含義。

#迭代 & 溝通

• 卓越源于迭代初稿總是很糟糕，但是編寫初稿是該過程的重要組成部分。要避免進度緩慢，很難-不好-> OK->好->好->鼓舞人心->超越。

• 在發(fā)布之前，請僅等到某事為“好”為止。社區(qū)將幫助你將其推向更深的鏈。

• 收到反饋時，盡量不要防御我們的寫作對我們來說可能是非常私人的，但是如果我們對幫助我們做得更好的人感到不滿，他們要么停止提供反饋，要么開始限制他們提供的反饋種類。

• 在向他人展示之前，請先閱讀自己的作品。如果你顯示某人的拼寫/語法錯誤很多，你將獲得有關拼寫語法/錯誤的反饋，而不是獲得有關寫作是否達到目標的更有價值的注釋。

• 當你要求人們提供反饋時，請告訴審閱者以下內容：

• 你正在嘗試做
• 你的恐懼是
• 你想要達到的平衡

• 當有人報告問題時，幾乎總是有問題，即使他們提出的解決方案不太正確。不斷詢問后續(xù)問題以了解更多信息

• 人們在提交/查看內容時需要放心地提問。這是你可以執(zhí)行的操作：

• 即使別人感到脾氣暴躁，也要感謝他們的貢獻/評價

。比如：

• “Great question！”
• “感謝你抽出寶貴的時間來解釋。????”
• “這實際上是故意的，但感謝你抽出寶貴的時間來貢獻自己的力量。 ????”

• 聽別人說什么，如果不確定自己是否正確理解，請照搬。這可以幫助驗證人們的感受和經(jīng)歷，同時還可以了解你是否正確理解了他們。

• 使用大量積極和善解人意的表情符號。顯得有些奇怪總比刻薄或急躁好。

• 請傳達規(guī)則/邊界。如果某人的舉止有辱人格/不當行為，請僅以仁慈和成熟來回應，但也要明確表示，這種行為是不可接受的，如果他們繼續(xù)表現(xiàn)不佳，將會發(fā)生什么 (根據(jù)行為準則)。

#提示、標注、警告和行高亮

我們有一些專用的樣式來表示需要以特定方式突出顯示的內容。這些被捕獲為在這個頁面請謹慎使用。

濫用這些樣式是有一定誘惑力的，因為你可以簡單地在標注中添加更改。但是，這會破壞用戶的閱讀流程，因此，只能在特殊情況下使用。在可能的情況下，我們應該嘗試在頁面內創(chuàng)建一個敘述和流程，以尊重讀者的認知負荷。

在任何情況下都不應該相鄰使用兩個警告，這表明我們無法很好地解釋上下文。

#貢獻

我們欣賞小型、集中的 PR。如果你想進行非常大的更改，請在發(fā)起請求之前與團隊成員溝通。這是一份詳細說明為什么這一點如此重要的書面材料讓我們在這個團隊里工作得很好。請理解，盡管我們總是很感激你的貢獻，但最終我們必須優(yōu)先考慮哪些對整個項目最有效。

#資源

#軟件

• Grammarly：用于檢查拼寫和語法的桌面應用程序和瀏覽器擴展 (盡管語法檢查不能捕獲所有內容，偶爾會顯示假陽性)。
• Code Spell Checker：一個 VS Code 的擴展，幫助你在降價和代碼示例中檢查拼寫。

#書籍

• On Writing Well (參見 popular quotes)
• Bird by Bird (參見 popular quotes)
• Cognitive Load Theory