設(shè)計(jì)系統(tǒng)「規(guī)范文檔」編寫指南 · 第一篇 - 文檔總覽

時(shí)間：2023-06-05 15:42:01 | 來源：網(wǎng)站運(yùn)營

時(shí)間：2023-06-05 15:42:01 來源：網(wǎng)站運(yùn)營

設(shè)計(jì)系統(tǒng)「規(guī)范文檔」編寫指南 · 第一篇 - 文檔總覽：

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

高質(zhì)量的規(guī)范文檔是一個(gè)優(yōu)秀設(shè)計(jì)系統(tǒng)的代表物。我們詳實(shí)地描述每個(gè) UI 組件的設(shè)計(jì)與代碼規(guī)范，來幫助設(shè)計(jì)師高效地作出決策，推動(dòng)開發(fā)速度。編寫高質(zhì)量的文檔需要前期規(guī)劃和一系列合理的流程來輔助，付出的成本相當(dāng)高。

這個(gè)系列由六篇文章組成，致力于描述編寫組件規(guī)范文檔的過程。本篇我會(huì)從目標(biāo)讀者、文檔內(nèi)容、文檔結(jié)構(gòu)開始。然后會(huì)涉及案例，設(shè)計(jì)與代碼指南。這些內(nèi)容來自于我自己這些年的實(shí)踐經(jīng)驗(yàn)以及社區(qū)里大家所分享的知識(shí)。




那么我以一個(gè)問題開始今天的主題：文檔的目標(biāo)讀者是誰，他們需要什么樣的內(nèi)容，作為編寫者我們該怎樣組織文檔結(jié)構(gòu)來作出清晰的表達(dá)？

文檔的目標(biāo)讀者

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

工程師，設(shè)計(jì)師，還有公司里的所有人！

當(dāng)一個(gè)設(shè)計(jì)系統(tǒng)包含了代碼指南，工程師們顯然會(huì)是讀者。那么一個(gè)只包含了代碼指南的設(shè)計(jì)系統(tǒng)應(yīng)該服務(wù)于設(shè)計(jì)師嗎？如果文檔里只包含了設(shè)計(jì)規(guī)范而沒有代碼（如 Material Design），工程師還是讀者嗎？




在我看來，兩個(gè)問題的答案都是肯定的。規(guī)范文檔是從不同的角度來服務(wù)于多種角色的。

除了設(shè)計(jì)與工程，它還服務(wù)于其他人嗎？很有可能，特別是當(dāng)文檔所在的設(shè)計(jì)系統(tǒng)已經(jīng)成為產(chǎn)品的基石時(shí)。簡短有效的介紹對(duì)于 PM（產(chǎn)品經(jīng)理） 很有價(jià)值，QA（測試） 則比較關(guān)注案例部分…等等。




很多設(shè)計(jì)系統(tǒng)團(tuán)隊(duì)還會(huì)把自己的系統(tǒng)公開出來，在體現(xiàn)共享精神的同時(shí)也能起到吸引行業(yè)人才的作用。所以文檔應(yīng)該能夠體現(xiàn)團(tuán)隊(duì)的專業(yè)與嚴(yán)謹(jǐn)。

文檔的主要目標(biāo)是：為設(shè)計(jì)師、工程師和團(tuán)隊(duì)里的其他角色服務(wù)，讓他們能夠高效地做決策。




Takeaway：設(shè)計(jì)系統(tǒng)的效應(yīng)和影響力不只覆蓋設(shè)計(jì)與工程，一個(gè)成長中的系統(tǒng)必將會(huì)服務(wù)于更多的角色。

工程師，接著是設(shè)計(jì)師，然后才是其他人

為所有角色服務(wù)并不意味著平等地服務(wù)所有角色。工程師每天會(huì)查閱 10 次或更多次文檔，他們甚至?xí)盐臋n與代碼編輯器窗口并排排列！設(shè)計(jì)師的訪問次數(shù)應(yīng)該是少于工程師的，其他角色則會(huì)更少。




所以誰是最重要的？以我的經(jīng)驗(yàn)來看，設(shè)計(jì)系統(tǒng)最初就是為了工程與設(shè)計(jì)之便，由工程師和設(shè)計(jì)師建立的。即使其他角色也對(duì)其有所貢獻(xiàn)，但他們?nèi)允瞧我?。因此我們首先需要確保工程師與設(shè)計(jì)師的需求能夠得到滿足。










那么，工程師與設(shè)計(jì)師孰輕孰重呢？我最近參與設(shè)計(jì)的設(shè)計(jì)系統(tǒng)項(xiàng)目中都需要同時(shí)服務(wù)于兩者，為設(shè)計(jì)和代碼制作規(guī)范指南。我也在一些企業(yè)的文檔中看到了對(duì)其中一方的過多偏見，或者是有將他們的目標(biāo)完全分離開的傾向（稍后我會(huì)解釋）。有很多維度需要考量：設(shè)計(jì)系統(tǒng)的目標(biāo)，他們的使用頻率，內(nèi)容深度、質(zhì)量、生產(chǎn)成本，以及和他們?nèi)粘９ぷ鞯南嚓P(guān)度。







Takeaway：讀者的優(yōu)先級(jí)由很多因素決定。要有預(yù)期：工程師和設(shè)計(jì)師的需求會(huì)有沖突，并盡可能地優(yōu)化和處理這些沖突。如果實(shí)在不行，就要偏向于距離最終產(chǎn)品最近的那一方，通常是工程師。這就意味著工程師優(yōu)先，設(shè)計(jì)師其次。

文檔內(nèi)容

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







抽象地來看，規(guī)范文檔的內(nèi)容通常包含以下四種模塊：

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

不同的模塊會(huì)有不同的制作成本

「介紹」寫起來當(dāng)然非常的短平快。結(jié)構(gòu)優(yōu)秀的「案例」也是值得投入成本的，并且寫起來會(huì)越來越順手。工程師也需要一個(gè)合理清晰的「代碼參考」。但是，真正有效的「設(shè)計(jì)參考」可能會(huì)非常耗費(fèi)成本。







Takeaway：規(guī)范文檔可以包含很多內(nèi)容模塊。所以需要團(tuán)隊(duì)在前期就進(jìn)行充分的討論，對(duì)每種內(nèi)容模塊做出符合自己團(tuán)隊(duì)和產(chǎn)品價(jià)值的判斷，再投入成本去制作。

文檔的信息結(jié)構(gòu)

設(shè)計(jì)與代碼：分開還是合并？

在實(shí)踐中，設(shè)計(jì)師往往會(huì)自顧自的發(fā)布或更新和自己相關(guān)的內(nèi)容，工程師也一樣。這樣的慣性行為會(huì)在無意中增加設(shè)計(jì)與工程的距離。所以大家需要在前期就對(duì)文檔的信息結(jié)構(gòu)達(dá)成共識(shí)。




谷歌的 Material 文檔生態(tài)就是這種距離感的代表。 Material’s design foundation 優(yōu)先服務(wù)于設(shè)計(jì)實(shí)踐, 而 Material Design Lite，Polymer Project，Android Developer’s，Material UI (built for React) 都是服務(wù)于代碼，和設(shè)計(jì)規(guī)范綁定的并不緊密。







這種分離的狀態(tài)其實(shí)是有意義和理由的。因?yàn)?Material 是一個(gè)操作系統(tǒng)的底層系統(tǒng)，跨越了許多框架，團(tuán)隊(duì)，平臺(tái)。它的復(fù)雜度在某種意義上超越了目前世界上所有的設(shè)計(jì)系統(tǒng)。但你要知道大多數(shù)的設(shè)計(jì)系統(tǒng)并不是服務(wù)于一個(gè)操作系統(tǒng)的，因此不會(huì)發(fā)展至如此復(fù)雜的形態(tài)。




對(duì)于像我們一樣的產(chǎn)品團(tuán)隊(duì)來說，設(shè)計(jì)和代碼分開是符合共識(shí)的。這種做法能夠給分別為兩種角色設(shè)計(jì)符合他們需求的體驗(yàn)。







這種做法也有風(fēng)險(xiǎn)。隨著時(shí)間推移，兩個(gè)網(wǎng)站可能出現(xiàn)不同步的現(xiàn)象：

• 設(shè)計(jì)與代碼的分類邏輯出現(xiàn)差異（最簡單的例子就是 Loader 和 Spinner 的命名：代碼里叫 Loader，而設(shè)計(jì)里則叫 Spinner）
• 功能差異：設(shè)計(jì)規(guī)范里出現(xiàn)了代碼不能實(shí)現(xiàn)的功能，或者代碼里加入了設(shè)計(jì)里沒有考慮的功能。

你可能會(huì)覺得這樣也挺好，畢竟設(shè)計(jì)和代碼本身就是兩個(gè)領(lǐng)域。至少對(duì)于文檔的寫作者來說這種分離還是挺方便的（只用考慮自己的需求，管理自己的進(jìn)度）。




但真正的讀者需要的是一個(gè)「真相的唯一來源（Single source of truth）」。如果你是一個(gè)對(duì)設(shè)計(jì)和代碼都有需求的讀者，你會(huì)發(fā)現(xiàn)自己不停在兩個(gè)網(wǎng)站間切換，兩個(gè)地方都有對(duì)你有價(jià)值的內(nèi)容，這感覺就像是在打網(wǎng)球時(shí)陷入了拉鋸戰(zhàn)。




Takeaway：要慎重地看待設(shè)計(jì)與代碼的分離。雖然一開始方便了內(nèi)容作者和發(fā)布者，但之后會(huì)有風(fēng)險(xiǎn)。這種做法也可能會(huì)在潛移默化中造成設(shè)計(jì)與工程的距離擴(kuò)大。

合并內(nèi)容的兩種方案：堆疊還是切換？

例如 Morningstar Design System 是把設(shè)計(jì)和代碼放在一個(gè)頁面里，讀者就能找到完全統(tǒng)一的命名，指南，功能描述。







堆疊式的布局方式會(huì)使得頁面變得冗長。當(dāng)然還有一種方式是使用 Tab 來切換內(nèi)容。







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

按類型來為內(nèi)容做排列和編組

不論選擇那種布局方式，文檔內(nèi)容的模塊結(jié)構(gòu)和順序應(yīng)該是保持一致的：

1. 簡介
2. 案例
3. 設(shè)計(jì)參考
4. 代碼參考

其實(shí)只要把「案例」放到讀者一進(jìn)來就能看到的地方，把設(shè)計(jì)和代碼參考放在一步點(diǎn)擊就能達(dá)到的地方，就是一個(gè)不錯(cuò)的設(shè)計(jì)了。下面是幾種行業(yè)內(nèi)比較有代表性的模式：

IBM Carbon 認(rèn)為代碼更應(yīng)該被優(yōu)先展示，將交互用法和樣式分別放在其他的 Tab 中。Hudl’s Uniform system 把順序反了過來，設(shè)計(jì)優(yōu)先于代碼。 Salesforce’s Lightning Design System 把代碼和組件案例放在 Tab 上方，默認(rèn)選中開發(fā)者指南這個(gè) Tab，而后兩個(gè) Tab 則被奇怪地留空了。




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

若頁面很長，則為讀者提供定位導(dǎo)航

你的文檔頁面越長，越需要給讀者清晰的認(rèn)知，要讓他們知道這個(gè)頁面里會(huì)包含哪些內(nèi)容以及當(dāng)前所處的位置?？v向的定位導(dǎo)航欄是個(gè)不錯(cuò)的方案：一直固定存在于頁面右側(cè)，在滾動(dòng)時(shí)同步追蹤位置，并且可以包含子標(biāo)題。




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

展示設(shè)計(jì)？展示代碼？還是都展示？

把設(shè)計(jì)和代碼融合，就會(huì)有讀者只對(duì)其中一個(gè)方面感興趣，他們會(huì)提出自己的意見：




設(shè)計(jì)負(fù)責(zé)人可能會(huì)問到：我能把這些代碼案例和指南隱藏掉嘛？

工程師可能會(huì)問：我能把這些和設(shè)計(jì)規(guī)范有關(guān)的文字隱藏掉嘛？




可以考慮加一個(gè)選項(xiàng)或按鈕來允許隱藏設(shè)計(jì)/代碼內(nèi)容。比如：

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

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




Hudl’s Uniform 就在頁面右上角放置了一個(gè) Toggle 來控制這兩種模式的開與關(guān)：




Takeaway：按內(nèi)容類型來梳理文檔結(jié)構(gòu)其實(shí)是個(gè)內(nèi)容管理方面的挑戰(zhàn)，并不是技術(shù)挑戰(zhàn)。你的信息結(jié)構(gòu)越嚴(yán)謹(jǐn)，成果就越優(yōu)秀，但是這依賴于高效的編寫和發(fā)布流程。




那么讀到這里的時(shí)候，你應(yīng)該對(duì)自己文檔的目標(biāo)讀者是誰有了合理的感知了，知道應(yīng)該在文檔中呈現(xiàn)哪些內(nèi)容，整體的結(jié)構(gòu)雛形也已經(jīng)形成。是時(shí)候開始工作啦?。ū酒辏?br>

---

設(shè)計(jì)系統(tǒng)專欄往期內(nèi)容：


VOL.01: UXPin Design System Virtual Summit 系列·第一篇