当美好的愿望遭遇现实
作为 Pennylane 的高级设计运营专家，我以为我们已经破解了设计文档的密码。我们基于 Notion 的系统全面、条理清晰，理论上堪称完美。
我们用来记录 Notion 上的设计系统组件的模板
在我的文章《设计文档：一致性和协作性 UI 开发的关键支柱》中，我倡导基于 Notion 的方法作为设计系统文档的黄金标准。回顾过去，那篇文章展现了我对文档的热情，但它也揭示了我对文档实际使用人员应该是什么样子的盲点。
在我原本以为只是例行检查设计和工程团队时，我突然意识到了这一点。结果，我听到的不是成功的故事，而是令人不安的事实：我们精心制作的文档，对于最需要它的人来说，基本上是隐形的。
一位前端工程师承认： “我通常只是尝试自己解决问题，这比在多个平台上搜索要快得多。”
“当我找到正确的文档时，我可能已经构建了该组件的三个版本，”另一位用户分享道。
这并不是我们团队能力的失败，而是我们的方法未能适应人们的实际工作方式。
改变一切的研究
之前，先简单介绍一下背景。设计师为空状态组件编写的文档是这样的：
工程师需要的技术文档是什么样的：
我没有为现有的文档辩护，而是决定倾听。几周来，我对设计和工程领域的20名团队成员进行了深入访谈。访谈结果清晰地展现了以下几个摩擦点：
来自设计师：
- 在截止日期的压力下，跨平台维护文档成为次要任务
- 后期反馈循环与工程团队产生了紧张关系
- 设计意图与技术实现之间的差距似乎难以逾越
来自工程师：
- 文档与编码环境脱节
- Figma 设计与实现的组件之间的视觉不一致造成了混乱
- 大量的文字解释无法与直接探索代码的即时性相媲美
- 多个事实来源导致决策瘫痪
根本原因是，我们创建了一个满足组织需求但忽略了用户自然工作流程的文档系统。
将文档重新想象为一种生活工具
解决方案不是编写更好的文档，而是从根本上重新思考文档是什么。
我们不需要要求团队适应我们的系统，如果我们的系统适应他们呢？
愿景：将文档从静态参考转变为决策制定过程中的动态、视觉伴侣。
我们的新理念：展示，而不是讲述
- 我们注重视觉优先的沟通，而非描述组件的外观，而是结合上下文进行展示。现在，每个组件都包含其默认状态、主要变体以及实际应用，一目了然。
- 工作流集成文档现已集成到 Figma 中，这是我们设计师日常使用的工具。无需再切换上下文，也无需跨平台搜索。
- 信息披露采用渐进式分层结构：重要细节预先呈现，必要时提供更深入的背景信息。团队可以根据自身情况灵活参与。
新的文档架构
组件标题
干净、简约、专注于基本要素、组件名称、实时代码的直接链接和完成状态。
Accordion 组件的新标题
视觉规格
以最纯净的形式显示的组件，其变体被清晰地标记，并由复杂分子的分离资产层支持。
组件文档的第一个面板：组件本身及其所有变体
情境指导
工艺技巧、行为文档和使用指南以视觉方式与交互式示例一起呈现。
表格组件的上下文指南
按照这里显示的顺序我们有：
- 内容指南链接，由我们的 UXW 作家创建并托管在 Notion 上
- 一些关于工艺技能的“技巧”，以促进持续改进并帮助团队采用先进的技术
- 对于具有水平滚动模式的表格，我们有尺寸指南和通用行为。此元素也可以在创建表格时用作模板
- 使用不同的颜色标记来表示与每条线的交互
- 调整列大小功能已记录为可在应用程序上实时使用
注意事项
一些多功能组件需要“注意事项”部分来说明使用它们的限制和最佳实践。
选择卡组件的注意事项部分
应用内示例
模板展示实际用例中的组件，弥合孤立组件和完整用户体验之间的差距。
在应用程序中使用 Accordion 组件的示例
最终结果
完整、全面的文档，一目了然，没有不必要的文本或过时的信息。
结果
反馈具有变革性：
“终于有符合我语言的文档了，”一位设计师分享道。 “我不用离开 Figma 就能看到我需要的一切。”
一位前端工程师表示： “这些可视化示例让我省去了与设计团队反复沟通的时间。我可以立即看到预期的行为。”
但真正的成功标准并非赞誉，而是使用率。我们的新文档正在被积极地查阅、在设计评审中被引用，并在工程讨论中被引用。它已经成为我们工作流程中不可或缺的一部分，而非事后才想到的。
建立在成功的基础上
这次旅程让我明白，优秀的文档就是在人们所在的地方与他们会面并支持他们自然的工作方式。
我们的下一个挑战是将这些相同的原则应用到我们的 UI 工具包平台，确保我们以工程为中心的工具像我们的设计文档一样直观且工作流程集成。
教训
这次转型最重要的启示在于人性。我们的利益相关者并不抗拒文档，他们抗拒的是那些无法满足他们需求的文档。
通过从同理心出发，进行真正的研究，并围绕实际工作流程而不是理论理想设计我们的文档系统，我们创造了一些不仅仅存在的东西：它蓬勃发展。
对其他设计团队的启示：你的文档的好坏取决于它的采用程度。在写下任何文字之前，先问问你的用户他们真正需要什么。答案可能会让你大吃一惊，并激发你彻底重新思考如何分享设计知识。
兰亭妙微(www.lanlanwork.com )是一家专注而深入的界面设计公司，为期望卓越的国内外企业提供卓越的大数据可视化界面设计、B端界面设计、桌面端界面设计、APP界面设计、图标定制、用户体验设计、交互设计、UI咨询、高端网站设计、平面设计，以及相关的软件开发服务，咨询电话：01063334945。我们建立了一个微信群，每天分享国内外优秀的设计，有兴趣请加入一起学习成长，咨询及进群请加蓝小助微信ben_lanlan。
