I wrote this article to document what I’m learning professionally while working on the new Garden Design System site in 2020. Like this article? Check out Defining Design System Principles.

我写这篇文章是为了记录我 在2020 年在新的 Garden Design System 网站 上工作时所学的专业知识 。喜欢这篇文章吗？ 查看 定义设计系统原理。

编写设计系统文档 (Writing design system documentation)

Creating effective documentation is a really important part of a design system. The key word there is effective. My experience with design system documentation is that there is rarely a shortage of information. Helping people understand how to use the system by presenting it in an organized and succinct fashion is the hard part.

创建有效的文档是设计系统中非常重要的部分。 那里的关键词是有效的。 我在设计系统文档方面的经验是，很少会缺少信息。 困难的部分是通过有组织的简洁方式来帮助人们了解如何使用该系统。

To make matters worse, design system documentation is a moving target. Standards and guidelines evolve over time with the products they serve. You don’t write it once and move on. You write it once and maintain it forever.

更糟糕的是，设计系统文档是一个不断发展的目标。 标准和指南随着它们所服务的产品的发展而发展。 您无需一次编写并继续前进。 您只需编写一次并永久保存。

I’m a designer by trade so to keep from getting overwhelmed with all these words flying around, I started to record practical tactics to use for auditing my own writing habits.

我是一名行业的设计师，因此为了避免被所有这些词语淹没而感到不知所措，我开始记录一些实用的策略，用于审核自己的写作习惯。

1.与作家合作 (1. Partner with a writer)

This is a rather odd tip to lead with for improving your writing but the hard truth is if you aren’t a UX writer or a content strategist, reading this blog post isn’t going to make you one. The tips below will help set a better foundation for communicating a cohesive vision, but most good practices I’ve learned (including these principles) are from writer feedback.

这是一个相当奇怪的尖端与提高你的写作，但残酷的事实是领导，如果你不是一个作家UX或内容策略，阅读这篇博客是不会让你一个。 以下提示将有助于为传达凝聚力的愿景奠定更好的基础，但是我所学到的大多数良好实践(包括这些原则)都来自作者的反馈。

It’s going to take the best parts of a lot of roles to craft effective design system documentation. That’s the point. It’s a combination of best practices from all the different disciplines in one place.

它将利用许多角色的最佳部分来编写有效的设计系统文档。 这才是重点。 它汇集了来自所有不同学科的最佳实践。

2.努力缩短一切 (2. Fight to shorten everything)

Time is money and documentation isn’t exactly riveting. Most readers are here to answer their question and leave — not read leisurely.

时间就是金钱，文档并没有完全吸引人。 大多数读者在这里回答他们的问题然后离开，而不是悠闲地阅读。

The single most important question I ask myself while editing is “Can I say the same thing with fewer words?”

我在编辑时问自己的最重要的一个问题是“ 我可以用更少的词说同样的话吗？ ”

带头示范 (Lead with examples)

If you find yourself trying to explain context, scenarios or applications — ask yourself “Would an example work better here?”. It gives readers relatable UI applications and it’s much easier to digest.

如果您发现自己试图解释上下文，场景或应用程序，请问自己“示例在这里能更好地工作吗？”。 它为读者提供了相关的UI应用程序，并且易于消化。

将大块文本分成列表 (Break up large blocks of text into a list)

Large blocks of paragraph copy can feel intimidating. Increase the scannability of dense paragraphs by formatting copy into lists.

大段的段落复制会让人感到恐惧。 通过将副本格式化为列表来提高密集段落的可扫描性。

Swift行动 (Prompt action)

Most readers are here looking for direction. Leading sentences with action verbs in an active voice is a good way to give clear direction and shorten copy at the same time.

大多数读者在这里寻找方向。 主动语态中带有动作动词的前导句子是给出清晰方向和缩短复制时间的好方法。

3.注意绝对 (3. Be mindful of absolutes)

Except in rare cases, avoid phrasing rules or guidelines with absolute adverbs.

除极少数情况外，请避免使用绝对副词表述规则或准则。

Saying a reader should “never” or “always” do something is a very difficult bar to set with absolute certainty.

说读者绝对不要“永远”或“总是”做某事是很难确定的。

The probability that there will be an exception to any given rule is high and this creates two problems:

任何给定规则都有例外的可能性很高，这会带来两个问题：

1. It creates a culture of rigid rulebook design thinking. The focus gets placed on following the rules instead of using educated judgement to craft a great experience.

   它创造了严格的规则书设计思维文化。 重点放在遵循规则上，而不是使用有根据的判断来创造出色的经验。

2. It trains readers to find loopholes. Every time an exception to an absolute rule is found it hurts the integrity of the documentation. Worse, it can make truly non-negotiable rules seem optional.

   它训练读者发现漏洞。 每次发现绝对规则的例外情况，都会损害文档的完整性。 更糟糕的是，它会使真正不可谈判的规则显得可选。

征求读者的判断 (Solicit a reader’s judgement)

Design systems serve to be assistive and empowering — not authoritarian. Providing direction with rationale can be more approachable than rigid rules without context. Consider prefacing direction with “It’s best to…”, “Avoid…” or “Consider…”. It accomplishes the same goal and doesn’t feel as domineering.

设计系统起辅助作用和赋权作用，而不是专制。 与没有上下文的严格规则相比，提供具有理论依据的指导可能更容易实现。 考虑使用“最好...”，“避免...”或“考虑...”作为开头。 它实现了相同的目标，而不是霸气。

Note: Too much rationale can make the documentation seem lengthy and daunting to read. Too little, and designers will feel like they are following an instruction manual. Finding a balance is difficult.

注意：太多的理由会使文档显得冗长且难以阅读。 太少了，设计人员会觉得自己正在遵循使用手册。 很难找到平衡。

4.偏爱正面而非负面 (4. Favor the positive over negative)

Lead with positive communication instead of focusing on bad practices. Repeatedly focusing on negative patterns to avoid can put a reader on the defensive.

以积极的沟通来领导，而不是专注于不良做法。 反复关注消极模式，避免使读者处于防御状态。

Note: There is a ton of valid and necessary reasons to advise not doing something. The primary point of this tip is to be mindful of finding a balance so the tone doesn’t feel accusatory or make the system feel oppressive.

注意：有很多正当和必要的理由建议不要做某事。 本技巧的主要目的是注意找到一个平衡点，以使语气不会让人感到责备或使系统感到压抑。

提供有利的替代方案 (Provide favorable alternatives)

When you use negative examples to illustrate a point, provide a favorable alternative. This helps the direction feel constructive instead of like a dead end.

当您使用负面示例来说明观点时，请提供一个有利的替代方法。 这有助于使方向感觉富有建设性，而不是死路一条。

5.有目的地写标题 (5. Write headlines with purpose)

Think of a headline as a singular point you are trying to make. Most readers are scanning headlines for key words on a problem they want to solve. Typically the more explicit you can be, the better.

将标题视为您要提出的奇点。 大多数读者都在头条新闻中搜索要解决的问题的关键词。 通常，您可以越明确，越好。

请记住，头条新闻也有实际用途 (Remember, headlines serve a practical purpose too)

For many documentation websites (including Garden) headlines play a practical role as well as a hierarchical one. Headlines get used in the URL so readers can link others to a specific section of any given page.

对于许多文档网站(包括花园)而言，头条新闻既起着实用的作用，又起着分层的作用。 URL中使用标题，因此读者可以将其他链接到任何给定页面的特定部分。

This means all headlines have an opportunity to give readers an idea of what they stand to learn from navigating to the URL. The more explicit you can be, the more shareable and accessible the entire site becomes. This is a win for page hierarchy, SEO and shareability simply by taking extra care in your headline verbiage.

这意味着所有标题都有机会使读者了解他们从导航到URL所学的内容。 您越明确，整个站点就越可共享和可访问。 仅需格外小心标题，就可以赢得页面层次结构，SEO和可共享性。

6.写作要赋权，而不要克制 (6. Write to empower, not restrain)

This last rule is more of a personal design system ethos than practical rule but it guides a lot of my approach to writing.

最后一条规则更多地是个人设计系统的精神，而不是实践规则，但它指导了我的许多写作方法。

To a design system with a hammer, everything looks like a nail.

对于带有锤子的设计系统，一切看起来都像钉子。

That is to say, I always try to be mindful the documentation isn’t becoming too prescriptive. Design systems are about empowering others with tools and information to improve upon what has already been built — not police against it.

就是说，我总是尽力注意文档并没有太规范。 设计系统是要赋予其他人以工具和信息的能力，以改进已构建的内容，而不是对它加以警告。

To be clear, deviations from established standards need to have merit. A lot of shared consideration, effort and learned usability is taken into account when writing design standards. Predictability is usability. Intuition is muscle memory. Those things must be respected.

需要明确的是，与既定标准的偏差是值得考虑的。 编写设计标准时，需要考虑很多共同的考虑因素，工作量和学习到的可用性。 可预测性就是可用性。 直觉是肌肉记忆。 这些事情必须得到尊重。

That said, a design system will not, and should not, contain an answer for every situation. At the end of the day a typical design system team has bandwidth to work on new documentation or police the old, but likely not both.

也就是说， 设计系统不会也不应包含每种情况的答案。 一天结束时，典型的设计系统团队有足够的带宽来处理新文档或管理旧文档，但可能两者都不是。

考虑维护成本 (Consider maintenance cost)

I’ve been to a lot of design systems conferences. There are usually a few foreboding themes the speakers touch on that I’ve grown to take to heart while editing:

我去过很多设计系统会议。 在编辑过程中，演讲者通常会想到一些令人难忘的主题：

1. Writing is hard but maintaining what you’ve written is exponentially more difficult

   写作很困难，但是保持所写内容的难度却成倍增加

2. Putting content in is easy, taking it out is really hard放入内容很容易，取出内容真的很困难

3. Even the most successful design systems have limits

   即使是最成功的设计系统也有局限性

最后的笔记 (Final notes)

There is no shortage of things to consider when writing effective documentation. If you want to learn more, here are a few of my favorite resources on the subject.

编写有效的文档时不乏需要考虑的事情。 如果您想了解更多，这里是我最喜欢的一些资源。

1. Documenting Components by Nathan Curtis

   内森·柯蒂斯(Nathan Curtis)的文档编制组件

2. Maintaining design systems by Brad Frost

   维护设计系统 ，作者：Brad Frost

3. Expressive Design Systems by Yesenia Perez-Cruz

   Yesenia Perez-Cruz的表现力设计系统

4. Everyday Information Architecture by Lisa Maria Marquis

   Lisa Maria Marquis的日常信息架构

Don’t forget to check out design.zendesk.com for more thought leadership, design process, and other creative musings.

不要忘记查看design.zendesk.com，以获取更多的思想领导力，设计流程和其他创意灵感。