開發者：蘋果，你的開發者文檔糟透了！
Chris Krycho 過去五年中一直在從事 JavaScript 前端開發的工作。過去幾個月時間裡，他一直在努力跟上蘋果開發者生態系統的發展速度，並且將這一切作為自己的 rewrite 項目中的一部分。（注：rewrite 是 Chris 的個人項目，目的是構建一個跨平臺的面向學術研究的寫作環境）
Chris 此前一直在學習 Swift 、 SwiftUI 以及 iOS 和 macOS API 等相關知識。於是他震驚了：
坦白講，蘋果生態系統的文檔完備度之低，讓我感到難以理解。作為一個使用過 AngularJS 、 Ember.js 的前端開發，Chris 表示：Ember 的文檔質量怎麼樣大家都懂的。但在他的四年實際使用中，他親眼見證了 Ember 的文檔從“勉強能用” 一路發展到“相當完善”。還有 AngularJS，五年前剛剛接觸它的 Chris 常常陷入崩潰：文檔嚴重缺少對核心概念的解釋，要麼就是解釋不知所云。他只能在絕望中求助他人，但他人通常也處於一種薛定諤的理解狀態，介於懂或不懂之間。
在我看來，對於開放 API 的大型科技企業來說，像 Ember、AngularJS 的文檔這樣，是一種糟糕甚至可怕的狀態。沒想到，Chris 還是太年輕。
蘋果才是文檔質量低下方面的 No.1，我所接觸的任何框架都不能與之匹敵……Chris 在蘋果平臺開發的感受，跟筆者的工作簽名頗為相似：Everyday Struggle。
在 Chris 看來，蘋果的開發平臺、工具裡，也就 Swift 還好一點，文檔寫得質量不錯，維護也相對到位。
但也就那樣了。大部分 SwiftUI 完全沒有文檔記錄，甚至沒有一行代碼解釋給定的類型或修飾符的作用。Swift Package Manager 的文檔還不錯，但是也很難從官方文檔中瞭解到它能做什麼，不能做什麼。Chris 的很多問題都只能面向 Stack Overflow 解決，他甚至不得不反覆閱讀那些 WWDC 大會上的文字材料，看看有沒有人提過跟他當前工作內容有關的信息。
他表示這種情況完全不合理：
在 Ember 生態系統中，我們有一條簡單的規則，即除非配有說明文檔，否則無法提交代碼。 Rust 也是如此（我曾經參與官方策略 rfc 的編寫工作）。而在親身接觸之後，我意識到蘋果的 API 開發人員（通常）不太清楚開源項目的運作方式——這可能是因為他們的交付流程不只涉及軟件，而是更多圍繞硬件產品進行。但無論如何，只要公開 API，那麼只有發佈對應的說明文檔，開發才算真正完成。
在 Chris 看來，這個鍋不能扣給某個單獨的軟件工程師，責任甚至也不再專門的文檔團隊成員。他認為，這純粹就是蘋果公司在工程組織方面的失敗。API 工程部門的人物，就是為使用 API 的受眾提供支持，蘋果的工程師肯定是希望同步提供對應的說明文檔的，但為什麼沒有呢？Chris 猜測一是該團隊人力嚴重不足，要麼就是蘋果公司的工程文化里根本就不重視文檔。
蘋果公司宣稱有意打造一套所有人都能夠使用的平臺，包括剛剛接觸編程的新人開發者，乃至擁有數十年開發經驗的老專家。但直到現在，蘋果也沒能真正實現這一目標。我已經擁有十年的軟件開發經驗，而且大部分成果都是通過具有豐富類型的系統與函數編程式語言開發完成的。我得承認，作為一名沒啥天賦的開發者，其中不少東西弄得我頭大如鬥、難以理解。我甚至不敢想象對於剛剛開始使用開發框架，或者僅僅接觸過 Ruby 、 Python 或者 JavaScript 等主流語言的新人來說，直接面對蘋果的這套生態系統到底是種怎樣的體驗。畢竟沒有了官方文檔，學習將成為一項不可能完成的任務。
所以蘋果公司，如果你真的希望開發人員愛上你家的平臺，那最好早點重視文檔完善工作，畢竟開發者是生態系統的命脈所在。如今這個時代，我們什麼都缺，但最不缺的就是開發生態選項。面對其他巨頭廠商的圍追堵截，你蘋果就真的毫不擔心？我不信。最後，希望蘋果能夠從其他框架及語言項目身上取取經：沒有文檔，不算完成，其實就這麼簡單。
網友怎麼看
Chris 的控訴得到了廣大蘋果生態下開發者們的聲援，他們紛紛表示：你不是一個人！
有的強調了文檔的重要性：
作為一個以文檔記錄工作為榮的人，我真的非常討厭在軟件開發中文檔的價值被嚴重低估。文檔常常會成就或打破一個產品。有的在分析為什麼沒人寫文檔：
我做過一段時間自由職業者，有一些公司找我幫忙寫文檔。相比起正式開發人員的高工資，這點錢比起來就是垃圾，所以我拒絕了。這說明什麼？這些公司要麼不重視文檔，要麼不給文檔團隊足夠的薪資，大概率也不會給足夠的時間。所以開發人員在構建環境時遇到這種問題，我一點都不奇怪。有分享自己用三分鐘放棄蘋果 API 故事的：
上週我開始了一個新項目，必須在 Spotify API 和 MusicKit JS API 之間做出選擇。Spotify 的文檔，我要什麼有什麼，蘋果的……大概是告訴了我什麼是“藝術家資源”。有的在批評蘋果公司的傲慢與自大：
蘋果似乎認為，只有他們才能掌握通往自己王國的所有鑰匙。第三方開發人員是沒有必要的，也不應該被信任。他們不允許開發者使用只有蘋果才能使用的平臺功能。它們沒有提供良好的文檔或開發工具。有的給蘋果支招，看看友商是怎麼做的：
看看微軟的 Xamarin ，人家用蘋果的 API 都比蘋果自己用得好。蘋果你就是自己不上心。蘋果要實在不想在文檔上投入精力，也可以學學微軟，讓第三方通過 GitHub 貢獻。（當然這種方式還是有一定問題，謹慎對待）如何才能寫出好的設計文檔？
程序員對文檔的態度有著一種矛盾的情感，一方面，需要依賴於文檔獲取相關開發知識，另一方面，又很少有人願意寫文檔。而不願意寫文檔的人群中，又有不少是因為不能結構化地輸出自己的開發知識。
讀文檔和寫文檔，一個輸入，一個輸出，一個讀者，一個作者。想要成為一個好程序員，有一個良好的知識結構是極其重要的。試著去用結構化的思維寫文檔吧，功在當代，利在千秋。
一篇好的文檔應該包含需求、設計目標、系統架構、模塊簡介、潛在風險等方面，在寫作上又應該遵循以下要點：
- 儘可能保持簡單；
- 添加圖表以可視化；
- 包含數字更為具體；
- 一定的趣味性讓文檔更耐讀；
- 做好自審，以評審者的角度去看文檔；
- 假期測試，看其他人能否讀懂、實現；
- 流程環節完備，關鍵人物參與其中；
你對文檔怎麼看？
閱讀更多 小智的互聯網觀察 的文章
