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

这篇译自 Nathan Curtis 的文章内容：Documenting Components

高品质的标准文档是一个出色设计系统软件的象征物。大家详实地叙述每一个 UI 部件的设计与代码标准，来协助设计师高效率地做出管理决策，促进开发设计速率。撰写高品质的文档必须早期整体规划和一系列有效的步骤来协助，投入的费用非常高。这一系列产品由六篇文章内容构成，专注于叙述撰写部件标准文档的全过程。这篇我能从总体目标读者、文档内容、文档构造逐渐。随后会涉及到实例，设计与代码手册。这种内容来自于自己这么多年的经验及其小区里大伙儿所介绍的专业知识。

那麼我终一个问题逐渐今日的主题风格：文档的总体目标读者到底是谁，她们必须怎样的内容，做为编写人大家该如何机构文档构造来做出清楚的表述？

文档的总体目标读者

最先：你需要搞清楚谁就是你的文档的关键读者。

工程师，设计师，也有公司里的每个人！

当一个设计系统软件涵盖了代码手册，工程师们显而易见会是读者。那麼一个只包括了代码手册的设计系统软件应当服务项目于设计师吗？假如文档里只包括了设计标准而沒有代码（如 Material Design），工程师或是读者吗？

我认为，2个问题的回答是一定的。标准文档是以不一样的方面来服務于多种多样人物的。

除开设计与工程项目，它还服务项目于别人吗？极有可能，尤其是当文档所属的设计系统软件已成为了商品的根基时。简洁明了合理的详细介绍针对 PM（产品运营） 很有使用价值，QA（检测） 则较为关心实例一部分…这些。

标准文档是以不一样的方面来服務于多种多样人物的

许多设计系统软件精英团队还会继续把自己的系统软件公开出来，在反映共享资源精神实质的并且也可以具有吸引住领域优秀人才的功效。因此文档应当能反映精英团队的专业与认真细致。

文档的具体目的是：为设计师、工程师和精英团队里的别的人物角色服务项目，让她们可以有效地做管理决策。

Takeaway：设计系统软件的效用和知名度不只遮盖设计与工程项目，一个发展中的系统软件必将会服务项目于大量的人物角色。

工程师，然后是设计师，随后才算是别人

为全部人物角色服务项目并不代表着公平地服务项目全部人物角色。工程师每日会查看 10 次或更多次文档，她们乃至会把文档与代码编辑软件对话框并列排序！设计师的浏览频次应该是低于工程师的，别的人物角色则会越来越少。

因此哪位最重要的？以我的工作经验看来，设计系统软件最开始便是为了更好地工程项目与设计之便，由工程师和设计师创建的。即使别的人物角色也对其有一定的奉献，但她们仍是偏主次的。因而大家最先必须保证 工程师与设计师的要求可以获得达到。

设计师与工程师优先最大

那麼，工程师与设计师分清是非呢？我近期参加设计的设计系统软件新项目里都必须与此同时服务项目于二者，为设计和代码制做标准手册。我就在一些公司的文档中看到了对在其中一方的太多成见，或是是有将它们的总体目标彻底分离去的趋向（稍候我能表述）。有很多层面必须考虑：设计系统软件的总体目标，她们的应用頻率，内容深层、品质、产品成本，及其和她们日常工作中的相关性。

设计师 vs 工程师

Takeaway：读者的等级由许多原因决策。要有预估：工程师和设计师的要求会出现矛盾，并尽量地改进和正确处理这种矛盾。假如确实不好，就需要偏重于间距最后商品近期的那一方，通常是工程师。这就代表着工程师优先选择，设计师次之。

文档内容

标准文档是联接读者与内容的媒体。内容会出现不一样的文件格式或控制模块，因而成本费也都各有差别，但你必须最后把他们编制在一起。

文档内容控制模块：介绍和实例文档内容控制模块：设计参照和代码参考

抽象地看来，标准文档的内容通常包括下列四种控制模块：

详细介绍：部件的名字，及其一段言简意赅的详细介绍。（必需）实例：这一模块的各类方式，情况，规格这些别的因素，比较好的作法是用代码立即把这种展现出去，而不是不能互动的静态图片。（必需）设计参照：例如何时需要用这一部件，容许的方法与不允许的作法，及其视觉效果、互动、创意文案层面的手册。（强烈推荐）代码参照：包括 API 和别的执行及布署领域的手册。（必需）

不一样的控制模块会出现不一样的设计成本费

「简介」写起來自然十分的稳准狠。构造出色的「实例」也是非常值得资金投入成本费的，而且写起來会愈来愈随手。工程师也必须一个有效清楚的「代码参照」。可是，真真正正合理的「设计参照」很有可能会十分消耗成本费。

横坐标：关键点的充足水平由浅到深。纵坐标：制做成本费由低到高

Takeaway：标准文档可以包括许多内容控制模块。因此必须精英团队在早期就开展多方面的探讨，对每一种内容控制模块作出合乎自身精英团队和产品价值的分辨，再资金投入成本费去制做。

文档的结构化分析

设计与代码：分离或是合拼？

在日常生活中，设计师通常会满不在乎的推送或升级和自身相应的内容，工程师也一样。那样的惯性力个人行为会在不经意中提升设计与工程项目的间距。因此我们要在早期就对文档的结构化分析达成一致。

Google的 Material 文档绿色生态便是这类陌生感的意味着。 Material’s design foundation 优先选择服务项目于设计实践活动, 而 Material Design Lite，Polymer Project，Android Developer’s，Material UI (built for React) 全是服务项目于代码，和设计标准关联的并不密切。

这类分离出来的情况实际上是更有意义和原因的。由于 Material 是一个电脑操作系统的底部系统软件，超越了很多架构，精英团队，服务平台。它的复杂性在某种程度上超过了现阶段全世界全部的设计系统软件。但你需要了解大部分的设计系统软件并非服務于一个系统的，因而不容易发展趋势至如此繁杂的形状。

针对像大家一样的设备精英团队而言，设计和代码分离是合乎的共识的。这类方法能给各自为二种人物角色设计合乎她们需要的感受。

部件设计标准与 API 和代码规范各自放到2个网站上。来源于：Atlassian

这类作法也是有风险性。伴随着时间流逝，2个网站很有可能产生不关联的状况：

设计与代码的归类逻辑性发生差别（非常简单的案例便是 Loader 和 Spinner 的取名：代码里叫 Loader，而设计里则叫 Spinner）作用差别：设计标准里发生了代码不可以完成的作用，或是代码里加进了设计里沒有考虑到的作用。

你也许会认为那样也挺不错，终究设计和代码自身是2个行业。最少针对文档的作者而言这类分离出来或是挺便捷的（仅用考虑到自身的要求，控制自己的进展）。

但真正意义上的读者必须的是一个「实情的唯一由来（Single source of truth）」。如果你是一个对设计和代码都是有要求的读者，你就会发现自身不断在2个网站间转换，2个地区都是有对您有使用价值的内容，这觉得就好似在打网球时深陷了消耗战。

Takeaway：要谨慎地对待设计与代码的分离出来。尽管一开始便捷了内容创作者和发送者，但以后会出现风险性。这类方法也有可能会在耳濡目染中导致设计与工程项目的间距扩张。

合拼内容的二种计划方案：层叠或是转换？

例如 Morningstar Design System 是把设计和代码放到一个界面里，读者就能寻找彻底统一的取名，手册，作用叙述。

一个网页页面之层叠式：把设计和代码放到一个网页中，竖向翻转来查询。

层叠式的布置方法会促使网页页面越来越冗杂。自然也有一种形式是应用 Tab 来转换内容。

一个网页页面之转换时：把设计和代码放到一个网页中，根据 Tab 来转换内容。

Takeaway：将设计和代码混和在一起是有可能的，大伙儿可以按自身的需要来挑选以上二种合理布局方法。

分类来为内容做排序和编队

无论挑选那类合理布局方法，文档内容的控制模块构造和次序应该是保持一致的：

介绍实例设计参照代码参考

实际上只需把「实例」放进读者一进去就能见到的地区，把设计和代码参照放到一步点一下就能做到的地区，便是一个很好的设计了。下边是几类领域内非常有象征性的方式：

左：IBM Carbon 模式 中：Hudl's Uniform System 方式 右：Lightning Design System 模式

IBM Carbon 觉得代码更应当被先行展现，将互动使用方法和款式各自放到其它的 Tab 中。Hudl’s Uniform system 把次序反了回来，设计优先选择于代码。 Salesforce’s Lightning Design System 把代码和部件实例放到 Tab 上边，默认设置选定开发人员手册这一 Tab，而后2个 Tab 则被怪异地空出了。

Takeaway：把介绍和实例放到一开始最重要的部位，下面的控制模块则沒有唯一的计划方案，必须我们自身作出合乎自身精英团队状况的分辨。

若网页页面较长，则为读者给予导航定位

你的文档网页页面越长，越必须给读者清楚的认知能力，要让她们了解这一网页页面里会含有什么内容及其目前所在的部位。竖向的导航定位栏是个很好的计划方案：一直固定不动存有于网页页面右边，在翻转时同歩跟踪部位，而且可以包括子标题。

Morningstar Design System 在文档网页页面右边设计了一个二级的导航定位栏

Takeaway：无论挑选哪一种方式，最重要的是在所有体系中维持逻辑性一致，合乎读者的期望与心理状态实体模型。

展现设计？展示代码？或是都展现？

把设计和代码结合，便会有读者只对在其中一个层面有兴趣，她们会提到自个的建议：

设计责任人很有可能会问起：我可以把这种代码实例和手册掩藏掉嘛？

工程师很有可能会问：我可以把这种和设计标准相关的文本掩藏掉嘛？

可以考虑到加一个选择项或按键来容许掩藏设计/代码内容。例如：

Design Only：把代码手册、代码精彩片段和特性表这些都掩藏起來

Code Only：把视觉效果款式规范和创意文案手册都掩藏，但依然要把一部分互动用法指南保存着，这对工程师们也有效。

Hudl’s Uniform 就在网页页面右上方置放了一个 Toggle 来操纵这2种方式的开与关：

Takeaway：按内容种类来整理文档构造实际上是个内容管理工作的挑戰，并非技术性挑戰。你的结构化分析越认真细致，成效就越出色，可是这取决于高效率的撰写和公布步骤。

那麼读到这儿的情况下，你应该对自身文档的总体目标读者到底是谁拥有有效的认知了，了解应当在文档中出现什么内容，总体的构造发展历程也早已产生。是时候逐渐工作啦！（这篇完）

设计系统软件栏目以往内容：

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

孙浩：GE Digital 客户体验主管与你讨论: 设计系统软件中的「一致性」与「操作灵活性」