面向開發者的網站，真的是認真設計過的嗎？

最近幾年，隨著技術產品化的流行，越來越多的公司（如雲廠商、開源軟體公司）將軟體提供給市場，2D（to Developer）成為了一種炙手可熱的商業 “風口”。所以，我們會看到各種面向開發者的網站以及各類的服務。

只不過，絕大多數的公司並沒有考慮開發者們的體驗，諸如於：

• 只需要在網站輕鬆點選三步，你就可以建立一個專案。呵，就不能提供個 CLI 一步到位嗎？
• 在頁面上拖拉拽就可以構建流水線。呵，就不能提供配置來修改嗎？
• 我們提供了高階搜尋功能，你需要選好你的條件，就能搜尋。呵，就不能提供表示式和示例嗎？
• ……

從傳統的意義上來說，這種設計也沒錯，面向新手開發嘛！只是，這樣的功能，新手用了一次之後還需要嗎？一個有經驗的新手，它需要的就是一系列更便捷的方式。

在這個關注於體驗的時代，我們還能設計好面向開發者的網站嗎？你們有考慮過開發者體驗設計嗎？

上半場：搜尋框的體驗設計

剛好，最近，我，一直糾結於一個搜尋框的設計。所以，先讓我們來看，兩類型別的不同搜尋框設計。

一個普通的搜尋框：面向普通使用者

因為不可描述的原因，我的部落格一直在 AWS 上，大概快有七八年了。同樣是一個搜尋功能，相比於某些公司，AWS 在這方面就能提供一個更好的體驗。通過 Option + S 就可以喚起搜尋框，隨後就可以到具體服務下的： Top features。

具體的服務提供得好不好另說。但是，這種：

• 還有能用的搜尋。更不用說有的雲廠商，連搜尋個 “AI” 都做不好？
• 適合於顯示器的字型與佈局。開發人員，誰沒有個大顯示器呢？
• 快捷鍵喚醒搜尋。老程式設計師，誰沒有過滑鼠手呢？

當然，AWS 這垃圾伺服器太貴了，大抵這就是智商稅。在傳統的 2B、2C 場景下，強業務方的公司裡，業務領導決定了一切，他們看不出平平無奇的 Google 搜尋框的背後花費了幾億，甚至於幾十億的成本，為的就是為幾十毫秒。而在 2D（to Developer）的場景下，開發人員完全可以看出這方面的技術水平和能力。

基於程式碼的搜尋框

最近，在開源軟體 ArchGuard 裡，我們實現了一個名為 Insight 的架構洞察功能的 PoC（概念驗證）。在這次驗證裡，我們參考了 SourceGraph 的搜尋設計，使用 Monaco Editor 構建了這個功能的搜尋框。結果，如下圖所示：

圖中的 field:dep_name == %dubbo% field:dep_version > 1.12.3 即為搜尋框。與搜尋功能相比，它更像是一個帶有搜尋功能的輸入框；然而，搜尋的方式是通過表示式的方式來進行。而為了更友好地支援 表示式 的輸入，表示式變成了一個程式碼編輯器。只有在程式碼編輯器裡，你才能自由地去書寫這種形式。

如果你有一定的前後端開發背景的話，那麼就能評估出這樣一個功能的工作量：

• 語法解析、高亮的輸入框。在 Monaco Editor 上自定義語言、語法解析、高亮、自動填充等。
• 自動關聯上下文。
• 表示式設計。
• 表示式合法性校驗。
• ……

後期，也非常有益於擴充套件，加一個新的欄位什麼的，完全不考驗設計人員，也不考慮開發人員。於是乎，在考慮了工作量和之後，選擇了這樣的一個方式（PS：在領導的角度，下面的方式看上去就非常高階）：

看上去還不錯，如果不新增新的欄位 —— 但是，新增新的欄位幾乎是 100%。也許是開發者的體驗都讓狗吃了，面向領導服務才更重要 —— 我見過其它更迷之設計，只是因為領導覺得程式碼化（配置化）的體驗對開發者不好。所以，總有公司會比 K8s 的配置化做成了表單……，不是嗎？

下半場：“狗” 看了都直搖頭的文件

首先，文件都是給不懂的人寫的，包括寫文件相關程式碼的人。其次，文件都是寫出那些出現 bug 的人，只要不出 bug，我就不需要看文件。

1. “啊，這個文件不錯，良心地給了個程式碼示例”
2. “等等，這是一個圖片”
3. ”嘿，我去找個圖片識別工具“
4. ”啊，這個圖片識別工具需要看一下文件“

好慘。

祈禱過程不出錯

每次在使用新的工具的時候，我總會期待我不會在過程中失手。然而，有時候會在最後一步，有時候它是在第一步。所以， 如果你的工具足夠穩定，你就不需要任何文件 。

而在用了文件之後，我選擇再試一次，並祈禱不出 bug。

以至於我至今懷疑，國內的新手程式設計師不看官方文件的習慣，可能源自於國內的公司給新手們一個印象：官方文件非常不靠譜。

讓人迷失的連結

在考慮平穩開發者體驗與文件體系的時候，我們通常會這麼考慮： 有意義的 URL 命名 。以便於構建一個網站-程式碼-文件相關聯的體系，即程式碼出錯可以找到文件，文件可以連結到網站

然而，使用國內的雲服務時，我經常丟失在文件的海洋裡。於是乎，我會有幾種方式解決：

• 自帶的文件搜尋。我沒見過，幾家公司能做好的，因為自己人都不用。
• Google / 百度搜索。說實話，在這一點，百度還是比 Google 好用，建議你使用另外一家的服務。
• ……

作為一箇中老年人，我儲存了這個地址在我的記事本里，以便於下次開啟的時候使用。於是，下次開啟記事本， 狗看了都就直搖頭 ：

• /document_detail/1364/53045.html
• /document_detail/1234/45678.html
• /document_detail/13432/23445.html

地址是哪個來著，微服務框架是哪一個連結來著？咦，這個連結怎麼失效了？要怪就怪微信不支援 URL preview。年輕大就是吃虧。

文件還需要體驗嗎？

類似的一些槽點就諸如於《 文件工程體驗設計：重塑開發者體驗 》所描述：

• 文件程式碼不同步。即文件的 API 變化可能落後於程式碼，導致 API 與文件出現不一致。
• 頻繁的 API 變更。API 變更時，文件需要手動進行更新，不能自動化同步。
• 概念不統一。對於同一個概念，文件的不同地方描述不一致。
• 重複的文件塊。文件需要重複引用某一部分的文件，不能像程式碼一樣引用。
• 程式碼無法執行。按照文件的步驟下來編寫的程式碼、複製的程式碼，是不能執行的。

簡單來說，就是人們從未把 文件當成一個工程 來考慮。當你把一個支撐域當成核心域的時候，那麼剩下的就自然而解了。

中場休息：UI vs CLI

我覺得這又是另外一個很有意思的話題：如果我們都用 CLI 的話，那麼誰來考慮 UI 的問題。不過，我反正是不想繼續吐槽了，前面都做不好……。

當然，在設計 CLI 的時候，還要考慮這個問題：

• CLI 的文件體驗設計。又繞回去了
• 服務更新時，是否提供自動遷移能力？
• CLI 的更新機制。
• ……

在不考慮將開發者的體驗作為第一優先順序時，我覺得沒有人會去考慮這些。要怪就怪程式設計師都鍛鍊得太刁鑽了 —— 誰讓他們就是寫體驗的人。

其它

咦，過頭來看，什麼是開發者？什麼是開發者的體驗設計？

所以，我覺得程式設計師都應該在顯示器下面放一個手辦，不是用來祈禱上線成功，而是用來祈禱自己不用寫文件 —— 這樣就不會被罵。