從無人閱讀的文檔到生動(dòng)的設(shè)計(jì)系統(tǒng)

2025-8-18 杰睿設(shè)計(jì)資源

當(dāng)美好的愿望遭遇現(xiàn)實(shí)

作為 Pennylane 的高級(jí)設(shè)計(jì)運(yùn)營專家，我以為我們已經(jīng)破解了設(shè)計(jì)文檔的密碼。我們基于 Notion 的系統(tǒng)全面、條理清晰，理論上堪稱完美。

我們用來記錄 Notion 上的設(shè)計(jì)系統(tǒng)組件的模板

在我的文章《設(shè)計(jì)文檔：一致性和協(xié)作性 UI 開發(fā)的關(guān)鍵支柱》中，我倡導(dǎo)基于 Notion 的方法作為設(shè)計(jì)系統(tǒng)文檔的黃金標(biāo)準(zhǔn)。回顧過去，那篇文章展現(xiàn)了我對(duì)文檔的熱情，但它也揭示了我對(duì)文檔實(shí)際使用人員應(yīng)該是什么樣子的盲點(diǎn)。

在我原本以為只是例行檢查設(shè)計(jì)和工程團(tuán)隊(duì)時(shí)，我突然意識(shí)到了這一點(diǎn)。結(jié)果，我聽到的不是成功的故事，而是令人不安的事實(shí)：我們精心制作的文檔，對(duì)于最需要它的人來說，基本上是隱形的。

一位前端工程師承認(rèn)： “我通常只是嘗試自己解決問題，這比在多個(gè)平臺(tái)上搜索要快得多。”

“當(dāng)我找到正確的文檔時(shí)，我可能已經(jīng)構(gòu)建了該組件的三個(gè)版本，”另一位用戶分享道。

這并不是我們團(tuán)隊(duì)能力的失敗，而是我們的方法未能適應(yīng)人們的實(shí)際工作方式。

改變一切的研究

之前，先簡(jiǎn)單介紹一下背景。設(shè)計(jì)師為空狀態(tài)組件編寫的文檔是這樣的：

工程師需要的技術(shù)文檔是什么樣的：

我沒有為現(xiàn)有的文檔辯護(hù)，而是決定傾聽。幾周來，我對(duì)設(shè)計(jì)和工程領(lǐng)域的20名團(tuán)隊(duì)成員進(jìn)行了深入訪談。訪談結(jié)果清晰地展現(xiàn)了以下幾個(gè)摩擦點(diǎn)：

來自設(shè)計(jì)師：

在截止日期的壓力下，跨平臺(tái)維護(hù)文檔成為次要任務(wù)
后期反饋循環(huán)與工程團(tuán)隊(duì)產(chǎn)生了緊張關(guān)系
設(shè)計(jì)意圖與技術(shù)實(shí)現(xiàn)之間的差距似乎難以逾越

來自工程師：

文檔與編碼環(huán)境脫節(jié)
Figma 設(shè)計(jì)與實(shí)現(xiàn)的組件之間的視覺不一致造成了混亂
大量的文字解釋無法與直接探索代碼的即時(shí)性相媲美
多個(gè)事實(shí)來源導(dǎo)致決策癱瘓

根本原因是，我們創(chuàng)建了一個(gè)滿足組織需求但忽略了用戶自然工作流程的文檔系統(tǒng)。

將文檔重新想象為一種生活工具

解決方案不是編寫更好的文檔，而是從根本上重新思考文檔是什么。

我們不需要要求團(tuán)隊(duì)適應(yīng)我們的系統(tǒng)，如果我們的系統(tǒng)適應(yīng)他們呢？

愿景：將文檔從靜態(tài)參考轉(zhuǎn)變?yōu)闆Q策制定過程中的動(dòng)態(tài)、視覺伴侶。

我們的新理念：展示，而不是講述

我們注重視覺優(yōu)先的溝通，而非描述組件的外觀，而是結(jié)合上下文進(jìn)行展示。現(xiàn)在，每個(gè)組件都包含其默認(rèn)狀態(tài)、主要變體以及實(shí)際應(yīng)用，一目了然。
工作流集成文檔現(xiàn)已集成到 Figma 中，這是我們?cè)O(shè)計(jì)師日常使用的工具。無需再切換上下文，也無需跨平臺(tái)搜索。
信息披露采用漸進(jìn)式分層結(jié)構(gòu)：重要細(xì)節(jié)預(yù)先呈現(xiàn)，必要時(shí)提供更深入的背景信息。團(tuán)隊(duì)可以根據(jù)自身情況靈活參與。