设计系统「规范文档」编写指南 · 第一篇 - 文档总览

时间：2023-06-05 15:42:01 | 来源：网站运营

时间：2023-06-05 15:42:01 来源：网站运营

设计系统「规范文档」编写指南 · 第一篇 - 文档总览：

本篇译自 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：按内容类型来梳理文档结构其实是个内容管理方面的挑战，并不是技术挑战。你的信息结构越严谨，成果就越优秀，但是这依赖于高效的编写和发布流程。




那么读到这里的时候，你应该对自己文档的目标读者是谁有了合理的感知了，知道应该在文档中呈现哪些内容，整体的结构雏形也已经形成。是时候开始工作啦！（本篇完）

---

设计系统专栏往期内容：


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