Vue.js 的官方文檔是不是太簡略了點？

01-06

很多細節沒有描述清楚，文檔沒有辦法做到自我解釋。難道說是默認要求讀者有一定的reactjs基礎嗎？比如說vue構造函數入參的render屬性，生成的不是實例本身而是它的一個子組件。這個就問題折騰了我整整一天。
還有vnode、單文件組件、jsx這些概念和功能，相應的說明太少了。

近期是 @趙錦江(勾三股四) 和我在維護 Vue.js 的官方中文文檔。勾股會把所有英文原站的更新儘快同步到中文站（這部分工作量很大，他剛給首頁新增的視頻加了字幕，還沒更新上去）；我會把現有的中文文檔內容全部重新 review 一遍，查漏補缺修繕一些有問題的翻譯，希望能提高一些翻譯質量，目前進行了快一半了。如有改進建議，請直接通過 GitHub issue 發起討論。

呵呵，伸手黨的要求真是越來越高了，開源不好做啊。

我覺得吧，這本質上是個情商問題。如果題主是真心想學，那就好好提問：「我覺得文檔中 render 函數的部分理解起來有些吃力，希望能有人幫忙解惑」，保證會得到完全不同的結果。然而你卻選擇了發泄你的負面情緒，把一切責任推給了文檔。

善意的提問，我自然會善意地回答。但我也不是聖人，抱怨發泄性質的提問，我忍不住了就要懟的。對這種態度報以善意，只會讓伸手黨覺得自己理所應當是大爺，社區的環境只會更差。

---

給一些吃瓜群眾的補充：Vue 的文檔很可能是所有前端項目里最用心的，比較過就知道。看到這個問題的感受大概就跟你辛辛苦苦加班做完了項目，PM 一臉嫌棄地跟你說『怎麼才做了這麼點功能』差不多。我跟各位貢獻者辛辛苦苦寫 + 翻譯的文檔免費給人看，還要被人抱怨，不好意思這個鍋我們不背。

原文：What it feels like to be an open-source maintainer

譯文：作為一名開源項目的維護者是一種什麼樣的體驗

數百人站在你家門口，耐心地等你去解決他們地問題，抱怨，合併代碼請求，新功能請求。

你想去幫助他們所有人，但是你現在正在推遲。可能你今天工作不順利，或者你累了，或者你只是想和家人朋友享受一個周末。
如果你去看一眼github上的通知，它總會提醒你有多少人在等。
當你安排出一些空閑時間，開門迎接第一位等待的人。這些人都是很好心的，他們嘗試使用你的項目但對API有些困惑，他們已經把代碼帖在Github評論里，但他們忘了或者是不知道怎麼去格式化代碼，所以他們的代碼真的是一團亂，難以閱讀。
幸運的是，你編輯他們的評論來添加一個代碼塊，代碼很好的格式化了，但仍然有一大堆代碼要去讀。
然而，他們對問題的描述難以理解。可能這個人的母語不是英語，或者他們不擅長通過文字進行交流，你也不確定是什麼原因。無論如何，你艱難地去理解他們所寫的段落。

看到後面還有上百人在排隊等候，你有些不耐煩了。你可以花費半小時去理解這個人的代碼，或者你可以僅僅瀏覽以下然後給出一些教程和文檔的鏈接，這很可能無法解決他們的問題。你也可以興奮的告訴他們去嘗試以下StackOverflow或者Slack的Channel。
下一個人皺著眉頭。說出一大堆的抱怨話，他們覺得由於你的某個API沒有按照公布的方式工作而浪費了他們生命中的兩個小時。他們的風涼話讓你想你心裡不爽。
你沒有在這個人身上浪費很多時間。你說：「這是一個開源項目，都是志願者在維護。如果代碼里有bug，請提交一個可再現的測試用例或者一個pull request。
下一個人遇到了一個很常見的錯誤。你知道之前已經見過這種錯誤好幾次了，但是想不起來解決方法在哪裡。StackOverflow？wiki？郵件列表？Google了一番之後，你貼出了個鏈接，關閉了這個問題。
下一位是一個普通的代碼貢獻者。你是通過各種社區論壇和兄弟項目認出他們的名字的。他們遇到了一個難解的問題，發送了一個代碼合併的請求來解決這個問題。不幸的是這個問題很複雜，他們的Pull Request用了不少篇幅來解釋這個問題。

你再一次瞄了一眼排隊等候的人。你知道這個人在他們的解決方法里做了很多工作，可能是一個合理的解決方案把。測試用例通過了，所以你冒險合併了這段代碼。
然而，你之前曾上過這樣的當。當時你沒有仔細評估就合併了一個Pull Request，最後由於一些你沒有考慮到的問題而引發一個小災難。通過了測試，但可能導致性能下降十分之一。或許它可能導致內存泄露。可能這個Pull Request使得API看起來更加複雜從而對新使用者造成很多困擾。
如果現在合併這個PR(Pull Request)，明天可能會遇到更多的問題，因為你可能為了解決某一個人的問題而破壞了別人的工作流。把這個問題先擱置在這，以後有時間了再解決。
下一個排隊的人發現了一個新BUG，你知道這BUG在另一個兄弟項目中頁存在。他們說這個BUG阻止了他們發布APP。你知道這是個大問題，但只是其中的一個，所以你現在沒有時間解決它。
你回答說這開起來確實是一個問題，也許開闢一個新倉庫更合適。所以你關閉了這個問題並把它拷貝到另一個倉庫里，添加了一條評論告訴他們應該仔細檢查哪部分代碼來修復bug。你不確定他們是否真的會按照你說的做。然而，大部分都沒有這麼做。

下一個人僅僅問了「現在是什麼情況？」。你不知道他們到底在說什麼，所以仔細看了以下上下文。他們在github上的一個項目中評論了一個長期存在的Bug，很多人不同意這個問題的解決方案，因此引發了很多討論。
在這個特殊的問題上有超過20條評論，看完所有評論會消耗很多時間，所以你僅僅回復了「對不起，這個問題存在有一段時間了，但還沒有人解決它。我們正在努力解決問題，要是有人解決了給我們發個代碼合併請求會是一個好的開始。
下一位的問題比較簡單。除了這個倉庫有一些古怪的測試數據。這些測試失敗的原因看起來很不真實，所以你必須重新運行來測試以下。你提醒自己等數據測試完成後再回過頭來仔細看看。
下一個人往那個很活躍的倉庫上提出了代碼合併請求，另一個維護者正在寫反饋，你大概瀏覽了一下，由於對另一位維護者比較信任，所以把這個問題設置為已讀，繼續往下看。
下一個人似乎遇到一個BUG，這個BUG你以前沒見過。不幸的是，他們提供的數據不充足：用的什麼瀏覽器？Node的版本是哪個？用的項目的哪個版本？他們在開發中使用了哪些代碼？你要求他們明確以下這些信息並關閉了這個標籤頁。

The constant stream
過了一會兒，你大概瀏覽了一二十個這樣的人。後面仍然有超過一百人。但是現在你覺得累了，每個人要麼是發抱怨，提問題，要麼是要求完善該項目。
從某種意義上來說，Github的通知功能展示的永遠都是你項目的消極的一面。當他們對你的工作感到滿意的時候就不會新建一個issue或者request。他們只有在發現不足之處的時候才會這麼做。即使你只花一點實踐來瀏覽這些通知，它也可能是你心理上和感情上感到疲憊。
你的伴侶注意到每當做完這些工作的時候都會變得脾氣暴躁。你可能發現自己毫無理由的沖她發火，僅僅是因為你自己心情不好。「如果做這些開源項目使你生氣，為什麼還要做呢？」她問。這時候你無法回答。
你可以休息以下了。事實上這使你自找的。過去，你為了自己的身心健康會從Github銷聲匿跡一兩周。但是你知道那樣做的結果就是現在的狀況：好幾百人排隊等候。
如果你僅僅保留Github通知里的最上面那些通知，可能就會只有20-30個issue需要處理了。然而你卻讓他們積累了起來，導致現在已經有好幾百個了，你覺得很有愧疚感。

過去，出於這樣或那樣的原因，你從來不讓issue累積起來。可能偶爾會見到一個issue被放置了幾個月都沒處理。你再次去處理的時候提出issue的那個不再回復你了，或者他們說他們用其他項目替代了你的項目從而解決了問題。那種感覺讓你覺得很糟，但是你也理解他們的難處。
你從經驗中得知對付陳舊的issue最實用的方法是告訴他們「我把舊的issue關了，如果你還沒有解決這個問題請再開一個issue或者提供更詳細的信息」。通常他們不再回復。有時候會回復也只是很生氣的表達他們等了這麼長時間。
所以現在你處理Github的通知更加勤奮了，數百人在排隊等候，你渴望有一天排隊的人減少到100以內，或者一打，甚至是神話般的0。所以你奮力前進。
吸引新的代碼貢獻者
就這樣處理了足夠多的issue，即使你真的到達了那個「零點」(即要處理的通知為零個)，你仍然還有一堆Bug沒有解決，還有很多代碼合併請求。加標籤可以有些幫助，比如給issue加上「需要新的版本」、「有測試案例」或者「添加第一個補丁」。「添加第一個補丁」這個標籤很有用，因為它經常會吸引新的貢獻者。
然而，你注意到吸引新貢獻者的那些issue都是簡單的問題，處理這些問題並且解釋它耗費的時間比你自己去解決所花費的時間更多。你明知是這樣卻還添加那些標籤，因為當你聽到別人說這是他第一次為開源項目做貢獻時你的心裡十分高興。
你知道他們很可能會提供反饋信息。一般這些人不會成為長期貢獻者或代碼維護者。你不知道這樣做是否正確，或許這樣做會吸引到一些真正的維護者來減輕你的負擔。

你有一個項目是可以自維護的。你已經好幾年沒碰它了，卻仍然有一群維護者來處理issue和PR。你非常感謝那些代碼維護者，但其他一些項目卻還是只能自己來維護。
向前看
你不願意去創建新的項目了，因為你知道這隻會增加你維護代碼的負擔。事實上，這裡有一個有悖常情的現象，你越成功，就會受到github通知的更多懲罰。
你仍然可以回憶起創造的興奮，東拼西湊寫個項目並解決了之前沒有被解決的問題時的喜悅之情。但是現在你根據經驗知道任何一個新的項目都會偷走你維護舊項目的時間。你有時候頁考慮是否把某箇舊項目正式標記為「不推薦使用」或者「不再維護」。
你不知道在自己崩潰之前還能撐多久。從跟那些以做開源項目為全職工作朋友聊天中，你知道把開源項目作為全職工作會允許你在某個項目上投入更多時間，你也考慮了這件事，但是這並不會給你很多幫助，因為你有幾十個開源項目競爭你的時間。
你最渴望的是有更多項目可以自維護。你盡量按照規範：詳細的配置說明，代碼風格，對那些提交優質PR的貢獻者更多的許可權。為每個項目做這些事情是挺累人的，也許是我不夠勤奮吧。

你知道開源更多的被認為是特權白人的排他性俱樂部，你對這感到遺憾，擔心自己在解決這件問題上做的不夠。
更重要的是，你感到愧疚：你明知道自己可以幫助一些人解決問題，但是你卻讓問題擱置數月然後關閉了它。你知道有些人是第一次對開源項目做貢獻但是你卻沒有回復他，這樣你可能就會打擊了他對開源的熱情，這也讓你感到愧疚。你對自己做的事感到愧疚，沒做的事也感到愧疚，因為你沒有招募新人來分享你這愧疚的體驗。
總結一下吧
我以上所述都是基於我個人的真實經歷。我說的並不代表所有從事開源軟體事業的人的心聲，但代表了和我有相同感受的人。
我從事開源事業大概七年了，也不願意這樣抱怨，因為我擔心這會被認為是誇張的抱怨。畢竟這些都是我自找的，我本可以隨時離開Github，我對別人沒有任何該履行的義務。
或許我還應該感到愉快呢？我在開源軟體方面的工作給了我現在在社區的地位。我獲得了在大會上發言的機會。Twitter上有數千粉絲，他們贊同並捍衛我的的觀點。可以說我之所以能在微軟公司有一份工作，都要歸功於我在開源方面的工作。我到底是在抱怨誰呢？
然而，我只要一些和我有相似感受的人都已經爆發了。之前他們都是熱心的合併代碼，解決問題，在博客上寫關於他們項目的文章，但是有一天他們突然消失了，你再也找不到他們了。對於這些人，我甚至懶得去在他們的代碼倉庫里新建一個issue，因為我知道他們肯定不會回復。我不是在指責他們，我只是擔心自己有天也會和他們一樣離開github。
我已經採取一些對我友好的措施了。我不使用Github通知的介面而是用郵件過濾器，所以能對這些通知根據項目(不維護的項目被忽略)或通知的類型(我曾發表過評論的具有較高的優先順序)進行分類。郵件也能支持離線工作和把所有東西集中起來。
對那些我已經停止維護的項目的問題的郵件我都標記為藍色(但是一般我仍然會每一個查看一次)，並且不予回復。我忽略博客的評論，StackOverflow的上回答的回復以及郵件列表裡的問題。我甚至對那些我覺得其他人已經維護的不錯的項目取消關注。
讓我感到沮喪的一個原因是解決這些issue消耗了我維護項目的時間。換句話說，雖然我經常僅僅回復「對不起我現在沒時間處理這個問題」，但這些回復也消耗掉我放在開源項目上的時間。
issue模板，GreenKeeper， travis_retry, Sauce Labs, 有這麼多針對開源項目的技術解決方案，我很感謝他們。如果沒有這些自動化工具我不能專心工作。從某種意義上來說你對一個issue提出反對，它造成的更多的是社交問題而不是技術問題。一個人這麼做還不會怎麼樣。我甚至還不是npm前100維護者就已經感覺到自己被壓榨。不能想像那些前100維護者的感受。
我甚至告訴我的妻子，等我們有了孩子，我從開源界退出。我不能想像自己如何能邊做開源邊撫養家庭。我猜測這最終會解決我的問題：唯一的選擇。我希望它能以一種正面的方式到來，就像開啟人生的新篇章，而不是以一種消極的方式，比如突然粗魯的爆發了。
結束語
如果你已經讀到這裡了並且對困擾開源社區的問題和解決方案感興趣，你可能會更想讀一下Nadia Eghbal所寫的一篇文章Roads and Bridges。這可能是最這個問題最透徹的分析了。
我樂於接受大家的建議，雖然我知道我很不情願在我的開源項目中把金錢和勞動力混為一談(可能是一些愚蠢的理想主義的原因)。但是我發現在其它項目中這方法很有用。
希望大家理解，雖然我上面表達了很多負面情緒，我仍然覺得開源是我人生中有價值的加分，我一點都不後悔。但我仍然希望這篇文章能讓大家知道成為自己成功的受害者的感受，以及被所有未完成工作拖累的感受。
如果我能從開源中學到一點東西的話，那就是：你做的工作越多，你得到的工作就越多。我覺得這個問題現在還沒有解決方案。

- 你有給項目捐贈過嗎？

- 沒有，你這項目會不會停止維護，我很擔心。

- 你有貢獻過代碼嗎？

- 沒有，你這項目會不會停止維護，畢竟是個人項目，表示很擔心。

- 你有幫忙翻譯過文檔嗎？

- 沒有，你這文檔有些問題，害我折騰了半天。

- 你有認真提過 issue 嗎？

- 肯定有，但作者老莫名其妙關了我的 issue。

呵呵。。

剛好你可以翻翻源代碼看看 api 的詳細調用。

或者看看 unit test 裡面的調用事例。

或者用用 Google StackOverflow 看看有沒有相關的問題或者文章。再不濟你也去提個 issue 問問你詳細的問題或者提出你希望完善的 api 文檔。

你都用到 render 函數了，相信也不是剛入行的菜鳥了吧？這點能力都沒有，還玩高階用法？

來知乎問這個問題除了引起互懟還能得到什麼？

就因為 Vue.js 作者上知乎？

你確定你看過avalon的文檔？

你沒看過webpack的文檔吧

我發現了，這將是React和webpack被黑的時候到了。

這位兄台你去看一下webpack或者angular4的文檔，他們的文檔看的想問候親戚，這麼說吧，簡單到遇到問題肯定查不到，必須google。

先上圖：看到沒？業界良心。貼心小棉襖！

簡單代表容易上手，對於新手來說比較友好，對於Vue框架本身來說，並沒有一上來就是webpack，ES6/7，typescript的，就簡單的一句話，需要有點js,css3,html5的基礎。文檔的思路非常清晰，先介紹Vue，框架內容，再拋出問題，讓學習者帶著問題去詳細的讀文檔，（有一種高中做英語閱讀題的感覺，先讀問題，再去找答案）這個思路是我見過最複合國情文檔了，不信你去看webpack的文檔。

我相信題豬並沒有說不好之意。確實有些概念對於新手來說不好理解，但是你可以暫時先不用管，比如render函數，jsx，伺服器渲染等等。實際開發的時候用的很少的。就拿jsx來說，作者弄的單文件組件(.vue文件)，推薦使用DOM模板。所以不要太那個了（找完小姐，轉身說小姐臟。。。。）。官方文檔大都是對於新手而言的，很多實際中出現的，還是需要靠自己長期積累。

還有就是Vue是國人唯一一個優秀的全世界通用的框架，大家要多支持，多交流溝通，現在已經不是外國的月亮圓的時代了。

最後，最後一句話：如果一個牛B 的東西，用簡單的方式表達出來，才是真正的好東西。祝好！

vue文檔已經做的很好了，目前可以說是我見過最好的開源項目文檔之一了。

很多開源項目你需要有一些相關領域基礎知識，如果沒有，還是請多去看看基礎知識再來。

開源社區其實很不歡迎題主這種態度的人，如果你換一種提問方式，如如何深入理解 vue中的render，估計會有很多人幫你。如果大家發現確實文檔沒寫到位，也會有人去修改文檔。但是你在這裡抱怨，就沒人幫你了。

請記住，這個世界上的開源項目都沒欠你什麼，社區用戶同樣沒欠你什麼，提問前請注意下自己態度

用 react 是把 react 的實現看了一遍才完全搞懂的。。。樓主能力太差

題主可以補充啊提pr啊，還有有些API不適宜暴露啊。要是什麼都暴露出來，肯定有人會覺得好複雜啊。

其實我建議vue可以學習一下Unreal，代碼隨便給，文檔要花錢。

@vczh 以前說過類似的問題，免費的東西就是這樣的，別人沒義務保證你有良好的用戶體驗。你感到某些地方不爽想吐槽一個，對方還會拿各種理由噴你伸手黨，活該學不好。

題主可以去 Gayhub 提 PR 充實文檔啊，也造福了別人不是。

js開源項目有文檔就不錯了

你一定沒看過react的文檔

Vue2.0的官方文檔很棒。。

Vue的文檔已經是業界良心了好吧，界面清爽，內容翔實。從題主的描述看來，學的吃力，明明是自己的問題，卻把氣撒到文檔上，這樣不好。

你一定沒看過React文檔 +1

假設你讀過React中文翻譯的文檔，請再讀一遍原文版React。你會有所新發現的（而且會發現全是新的）

Vue的文檔已經特別清晰了，你可能姿勢不對。你應該像小學三年級翻新華字典一樣去查。而且是少有的官方中文文檔，已經特別舒服了。

別說什麼vue也是社區翻譯的，至少那是欽定的社區翻譯！

開源社區用戶價值依次增大

- 0 +

-------------|------------------------------------------------------------&>

到社區抱怨默默自己解決到項目提issue 給出乾淨復現提PR