當美好的愿望遭遇現實 作為 Pennylane 的高級設計運營專家，我以為我們已經破解了設計文檔的密碼。我們基于 Notion 的系統全面、條理清晰，理論上堪稱完美。
我們用來記錄 Notion 上的設計系統組件的模板
在我的文章 《設計文檔：一致性和協作性 UI 開發的關鍵支柱》 中，我倡導基于 Notion 的方法作為設計系統文檔的黃金標準。回顧過去，那篇文章展現了我對文檔的熱情，但它也揭示了我對文檔實際使用人員應該是 什么 樣子 的盲點。
在我原本以為只是例行檢查設計和工程團隊時，我突然意識到了這一點。結果，我聽到的不是成功的故事，而是令人不安的事實：我們精心制作的文檔，對于最需要它的人來說，基本上是隱形的。
一位前端工程師承認： “我通常只是嘗試自己解決問題，這比在多個平臺上搜索要快得多。”
“當我找到正確的文檔時，我可能已經構建了該組件的三個版本，” 另一位用戶分享道。
這并不是我們團隊能力的失敗，而是我們的方法未能適應人們的實際工作方式。
改變一切的研究 之前，先簡單介紹一下背景。設計師為空狀態組件編寫的文檔是這樣的：
工程師需要的技術文檔是什么樣的：
我沒有為現有的文檔辯護，而是決定傾聽。幾周來，我對設計和工程領域的20名團隊成員進行了深入訪談。訪談結果清晰地展現了以下幾個摩擦點：
來自設計師：
在截止日期的壓力下，跨平臺維護文檔成為次要任務 后期反饋循環與工程團隊產生了緊張關系 設計意圖與技術實現之間的差距似乎難以逾越
來自工程師：
文檔與編碼環境脫節 Figma 設計與實現的組件之間的視覺不一致造成了混亂 大量的文字解釋無法與直接探索代碼的即時性相媲美 多個事實來源導致決策癱瘓
根本原因是，我們創建了一個滿足組織需求但忽略了用戶自然工作流程的文檔系統。
將文檔重新想象為一種生活工具 解決方案不是編寫更好的文檔，而是從根本上重新思考文檔是什么。
我們不需要要求團隊適應我們的系統，如果我們的系統適應他們呢？
愿景：將文檔從靜態參考轉變為決策制定過程中的動態、視覺伴侶。
我們的新理念：展示，而不是講述
我們注重視覺優先的溝通， 而非描述組件的外觀，而是結合上下文進行展示。現在，每個組件都包含其默認狀態、主要變體以及實際應用，一目了然。 工作流集成文檔 現已集成到 Figma 中，這是我們設計師日常使用的工具。無需再切換上下文，也無需跨平臺搜索。 信息披露 采用漸進式分層結構：重要細節預先呈現，必要時提供更深入的背景信息。團隊可以根據自身情況靈活參與。
新的文檔架構 組件標題 干凈、簡約、專注于基本要素、組件名稱、實時代碼的直接鏈接和完成狀態。
Accordion 組件的新標題
視覺規格 以最純凈的形式顯示的組件，其變體被清晰地標記，并由復雜分子的分離資產層支持。
組件文檔的第一個面板：組件本身及其所有變體
情境指導 工藝技巧、行為文檔和使用指南以視覺方式與交互式示例一起呈現。
表格組件的上下文指南
按照這里顯示的順序我們有：
內容指南鏈接，由我們的 UXW 作家創建并托管在 Notion 上 一些關于工藝技能的“技巧”，以促進持續改進并幫助團隊采用先進的技術 對于具有水平滾動模式的表格，我們有尺寸指南和通用行為。此元素也可以在創建表格時用作模板 使用不同的顏色標記來表示與每條線的交互 調整列大小功能已記錄為可在應用程序上實時使用
注意事項 一些多功能組件需要“注意事項”部分來說明使用它們的限制和最佳實踐。
選擇卡組件的注意事項部分
應用內示例 模板展示實際用例中的組件，彌合孤立組件和完整用戶體驗之間的差距。
在應用程序中使用 Accordion 組件的示例
最終結果 完整、全面的文檔，一目了然，沒有不必要的文本或過時的信息。
結果 反饋具有變革性：
“終于有符合我語言的文檔了，” 一位設計師分享道。 “我不用離開 Figma 就能看到我需要的一切。”
一位前端工程師表示： “這些可視化示例讓我省去了與設計團隊反復溝通的時間。我可以立即看到預期的行為。”
但真正的成功標準并非贊譽，而是使用率。我們的新文檔正在被積極地查閱、在設計評審中被引用，并在工程討論中被引用。它已經成為我們工作流程中不可或缺的一部分，而非事后才想到的。
建立在成功的基礎上 這次旅程讓我明白，優秀的文檔就是在人們所在的地方與他們會面并支持他們自然的工作方式。
我們的下一個挑戰是將這些相同的原則應用到我們的 UI 工具包平臺，確保我們以工程為中心的工具像我們的設計文檔一樣直觀且工作流程集成。
教訓 這次轉型最重要的啟示在于人性。我們的利益相關者并不抗拒文檔，他們抗拒的是那些無法滿足他們需求的文檔。
通過從同理心出發，進行真正的研究，并圍繞實際工作流程而不是理論理想設計我們的文檔系統，我們創造了一些不僅僅存在的東西：它蓬勃發展。
對其他設計團隊的啟示： 你的文檔的好壞取決于它的采用程度。在寫下任何文字之前，先問問你的用戶他們真正需要什么。答案可能會讓你大吃一驚，并激發你徹底重新思考如何分享設計知識。
蘭亭妙微( www.ocunn.cn )是一家專注而深入的界面設計公司，為期望卓越的國內外企業提供卓越的大數據可視化界面設計 、B端界面設計 、桌面端界面設計 、APP界面設計 、圖標定制 、用戶體驗設計 、交互設計 、UI咨詢 、高端網站設計 、平面設計 ，以及相關的軟件開發服務，咨詢電話：01063334945。我們建立了一個微信群，每天分享國內外優秀的設計，有興趣請加入一起學習成長，咨詢及進群請加藍小助微信ben_lanlan。
