Vue 3.0文檔編寫指南

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

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

#原則

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

#組織

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

#寫作 & 語法

#風(fēng)格

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

#語法

• 避免縮寫在編寫代碼和示例代碼中 (例如，attribute 優(yōu)于 attr，message 優(yōu)于 msg)，除非你在 API 中明確引用了縮寫 (例如 $attrs)。標(biāo)準(zhǔn)鍵盤上包含的縮寫符號(hào) (例如，@，#，&) 可以。
• 當(dāng)引用直接下面的示例時(shí)，請使用冒號(hào) (:) 結(jié)束句子，而不是句點(diǎn) (.)
• 使用牛津逗號(hào) (；例如：“a，b，and c”替換“a，b and c”)。！為什么牛津逗號(hào)很重要
  • 來源：The Serial (Oxford) Comma：When and Why To Use It
• 引用項(xiàng)目名稱時(shí)，請使用項(xiàng)目引用自身的名稱。例如，“webpack”和“npm”都應(yīng)使用小寫字母，因?yàn)檫@是它們的文檔引用它們的方式。
• 使用標(biāo)題大小寫作為標(biāo)題 - 至少到目前為止，因?yàn)檫@是我們在其余文檔中使用的。有研究表明，句子大小寫 (僅標(biāo)題的第一個(gè)單詞以大寫字母開頭) 實(shí)際上在可讀性上是優(yōu)越的，并且還減少了文檔作者的認(rèn)知開銷，因?yàn)樗麄儾槐赜涀∈欠褚髮憽癮nd”，“with”和“about”。
• 請勿使用表情符號(hào) (討論中除外)。Emoji 既可愛又友好，但是它們可能會(huì)使文檔分散注意力，有些表情符號(hào)甚至?xí)诓煌幕袀鬟_(dá)不同的含義。

#迭代 & 溝通

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

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

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

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

• 當(dāng)你要求人們提供反饋時(shí)，請告訴審閱者以下內(nèi)容：

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

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

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

• 即使別人感到脾氣暴躁，也要感謝他們的貢獻(xiàn)/評價(jià)

。比如：

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

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

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

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

#提示、標(biāo)注、警告和行高亮

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

濫用這些樣式是有一定誘惑力的，因?yàn)槟憧梢院唵蔚卦跇?biāo)注中添加更改。但是，這會(huì)破壞用戶的閱讀流程，因此，只能在特殊情況下使用。在可能的情況下，我們應(yīng)該嘗試在頁面內(nèi)創(chuàng)建一個(gè)敘述和流程，以尊重讀者的認(rèn)知負(fù)荷。

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

#貢獻(xiàn)

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

#資源

#軟件

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

#書籍

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