設計系統「規範文檔」編寫指南 · 第一篇

本篇譯自 Nathan Curtis 的文章：Documenting Components

高質量的規範文檔是一個優秀設計系統的代表物。我們詳實地描述每個 UI 組件的設計與代碼規範，來幫助設計師高效地作出決策，推動開發速度。編寫高質量的文檔需要前期規劃和一系列合理的流程來輔助，付出的成本相當高。

那麼我以一個問題開始今天的主題：文檔的目標讀者是誰，他們需要什麼樣的內容，作為編寫者我們該怎樣組織文檔結構來作出清晰的表達？

文檔的目標讀者

首先：你要弄清楚誰是你的文檔的主要讀者。

工程師，設計師，還有公司里的所有人！

當一個設計系統包含了代碼指南，工程師們顯然會是讀者。那麼一個只包含了代碼指南的設計系統應該服務於設計師嗎？如果文檔里只包含了設計規範而沒有代碼（如 Material Design），工程師還是讀者嗎？

在我看來，兩個問題的答案都是肯定的。規範文檔是從不同的角度來服務於多種角色的。

除了設計與工程，它還服務於其他人嗎？很有可能，特別是當文檔所在的設計系統已經成為產品的基石時。簡短有效的介紹對於 PM（產品經理） 很有價值，QA（測試） 則比較關注案例部分…等等。

很多設計系統團隊還會把自己的系統公開出來，在體現共享精神的同時也能起到吸引行業人才的作用。所以文檔應該能夠體現團隊的專業與嚴謹。

文檔的主要目標是：為設計師、工程師和團隊里的其他角色服務，讓他們能夠高效地做決策。

Takeaway：設計系統的效應和影響力不只覆蓋設計與工程，一個成長中的系統必將會服務於更多的角色。

工程師，接著是設計師，然後才是其他人

為所有角色服務並不意味著平等地服務所有角色。工程師每天會查閱 10 次或更多次文檔，他們甚至會把文檔與代碼編輯器窗口並排排列！設計師的訪問次數應該是少於工程師的，其他角色則會更少。

所以誰是最重要的？以我的經驗來看，設計系統最初就是為了工程與設計之便，由工程師和設計師建立的。即使其他角色也對其有所貢獻，但他們仍是偏次要的。因此我們首先需要確保工程師與設計師的需求能夠得到滿足。

那麼，工程師與設計師孰輕孰重呢？我最近參與設計的設計系統項目中都需要同時服務於兩者，為設計和代碼製作規範指南。我也在一些企業的文檔中看到了對其中一方的過多偏見，或者是有將他們的目標完全分離開的傾向（稍後我會解釋）。有很多維度需要考量：設計系統的目標，他們的使用頻率，內容深度、質量、生產成本，以及和他們日常工作的相關度。

Takeaway：讀者的優先順序由很多因素決定。要有預期：工程師和設計師的需求會有衝突，並儘可能地優化和處理這些衝突。如果實在不行，就要偏向於距離最終產品最近的那一方，通常是工程師。這就意味著工程師優先，設計師其次。

文檔內容

規範文檔是連接讀者與內容的媒介。內容會有不同的格式或模塊，因此成本也各有差異，而你需要最終把它們編織在一起。

抽象地來看，規範文檔的內容通常包含以下四種模塊：

1. 介紹：組件的名稱，以及一段簡明扼要的介紹。（必要）
2. 案例：這個組件的各種形式，狀態，尺寸等等其他要素，比較好的做法是用代碼直接把這些展示出來，而不是不可以交互的靜態圖片。（必要）
3. 設計參考：比如什麼時候應該用這個組件，允許的做法與不允許的做法，以及視覺、交互、文案方面的指南。（推薦）
4. 代碼參考：包含 API 和其他實施及部署方面的指南。（必要）

不同的模塊會有不同的製作成本

「介紹」寫起來當然非常的短平快。結構優秀的「案例」也是值得投入成本的，並且寫起來會越來越順手。工程師也需要一個合理清晰的「代碼參考」。但是，真正有效的「設計參考」可能會非常耗費成本。

Takeaway：規範文檔可以包含很多內容模塊。所以需要團隊在前期就進行充分的討論，對每種內容模塊做出符合自己團隊和產品價值的判斷，再投入成本去製作。

文檔的信息結構

設計與代碼：分開還是合併？

在實踐中，設計師往往會自顧自的發布或更新和自己相關的內容，工程師也一樣。這樣的慣性行為會在無意中增加設計與工程的距離。所以大家需要在前期就對文檔的信息結構達成共識。

谷歌的 Material 文檔生態就是這種距離感的代表。 Material』s design foundation 優先服務於設計實踐, 而 Material Design Lite，Polymer Project，Android Developer』s，Material UI (built for React) 都是服務於代碼，和設計規範綁定的並不緊密。

這種分離的狀態其實是有意義和理由的。因為 Material 是一個操作系統的底層系統，跨越了許多框架，團隊，平台。它的複雜度在某種意義上超越了目前世界上所有的設計系統。但你要知道大多數的設計系統並不是服務於一個操作系統的，因此不會發展至如此複雜的形態。

對於像我們一樣的產品團隊來說，設計和代碼分開是符合共識的。這種做法能夠給分別為兩種角色設計符合他們需求的體驗。

這種做法也有風險。隨著時間推移，兩個網站可能出現不同步的現象：

• 設計與代碼的分類邏輯出現差異（最簡單的例子就是 Loader 和 Spinner 的命名：代碼里叫 Loader，而設計里則叫 Spinner）
• 功能差異：設計規範里出現了代碼不能實現的功能，或者代碼里加入了設計里沒有考慮的功能。

你可能會覺得這樣也挺好，畢竟設計和代碼本身就是兩個領域。至少對於文檔的寫作者來說這種分離還是挺方便的（只用考慮自己的需求，管理自己的進度）。

但真正的讀者需要的是一個「真相的唯一來源（Single source of truth）」。如果你是一個對設計和代碼都有需求的讀者，你會發現自己不停在兩個網站間切換，兩個地方都有對你有價值的內容，這感覺就像是在打網球時陷入了拉鋸戰。

Takeaway：要慎重地看待設計與代碼的分離。雖然一開始方便了內容作者和發布者，但之後會有風險。這種做法也可能會在潛移默化中造成設計與工程的距離擴大。

合併內容的兩種方案：堆疊還是切換？

例如 Morningstar Design System 是把設計和代碼放在一個頁面里，讀者就能找到完全統一的命名，指南，功能描述。

堆疊式的布局方式會使得頁面變得冗長。當然還有一種方式是使用 Tab 來切換內容。

Takeaway：將設計和代碼混合在一起是有可能的，大家可以按自己的需求來選擇以上兩種布局方式。

按類型來為內容做排列和編組

不論選擇那種布局方式，文檔內容的模塊結構和順序應該是保持一致的：

1. 簡介
2. 案例
3. 設計參考
4. 代碼參考

其實只要把「案例」放到讀者一進來就能看到的地方，把設計和代碼參考放在一步點擊就能達到的地方，就是一個不錯的設計了。下面是幾種行業內比較有代表性的模式：

IBM Carbon 認為代碼更應該被優先展示，將交互用法和樣式分別放在其他的 Tab 中。Hudl』s Uniform system 把順序反了過來，設計優先於代碼。 Salesforce』s Lightning Design System 把代碼和組件案例放在 Tab 上方，默認選中開發者指南這個 Tab，而後兩個 Tab 則被奇怪地留空了。

Takeaway：把簡介和案例放在一開始最重要的位置，接下來的模塊則沒有唯一的方案，需要大家自己做出符合自己團隊情況的判斷。

若頁面很長，則為讀者提供定位導航

你的文檔頁面越長，越需要給讀者清晰的認知，要讓他們知道這個頁面里會包含哪些內容以及當前所處的位置。縱向的定位導航欄是個不錯的方案：一直固定存在於頁面右側，在滾動時同步追蹤位置，並且可以包含子標題。

Takeaway：不論選擇哪種形式，最重要的是在整個系統中保持邏輯一致，符合讀者的預期與心理模型。

展示設計？展示代碼？還是都展示？

把設計和代碼融合，就會有讀者只對其中一個方面感興趣，他們會提出自己的意見：

設計負責人可能會問到：我能把這些代碼案例和指南隱藏掉嘛？

工程師可能會問：我能把這些和設計規範有關的文字隱藏掉嘛？

可以考慮加一個選項或按鈕來允許隱藏設計/代碼內容。比如：

Design Only：把代碼指南、代碼片段和屬性表等等都隱藏起來

Code Only：把視覺樣式指南和文案指南都隱藏，但還是要把一部分交互用法指南保留著，這對工程師們也有用。

Hudl』s Uniform 就在頁面右上角放置了一個 Toggle 來控制這兩種模式的開與關：

Takeaway：按內容類型來梳理文檔結構其實是個內容管理方面的挑戰，並不是技術挑戰。你的信息結構越嚴謹，成果就越優秀，但是這依賴於高效的編寫和發布流程。

那麼讀到這裡的時候，你應該對自己文檔的目標讀者是誰有了合理的感知了，知道應該在文檔中呈現哪些內容，整體的結構雛形也已經形成。是時候開始工作啦！（本篇完）

原文地址：