ARTICLE · 1121487
什么成就了文档之美?
好文精选翻译，原文链接
https://passo.uno/what-makes-docs-beautiful/
文档常常被视为纯粹的功能性产物，是一堆内容。当它运作良好时，根本不会被人记住。然而，阅读文档的人能够分辨出，哪本手册或哪个文档网站更能让他们在心灵和感官上感到愉悦。我们都体验过那种读来顺畅和读来艰涩的页面所带来的不同感受。
那么，如果我们都认同文档可以成为一种产品，为什么不去追求以取悦使用者的方式来构建它们呢？如果文档是产品的入口，那它们难道不应该产生一种积极的感受，让用户更愿意频繁回访、更加信任它们吗？好的文档，能让用户感到自己更有能力，或者让他们有所收获。是能够治愈（用户问题）的文档。
什么因素能让文档变得优美，这是一个重要的问题，尤其是在当今这个时代，文档正面临着被大型语言模型大量生产的风险，而这些模型既不具备品味，也没有能力去辨别文档的优劣。我写这篇文章，旨在抛砖引玉，引发讨论，或许也能给我自己带来一些启发。
在技术写作的讨论中，“美”几乎总是缺席的
我发现关于“美”和文档之间关系的探讨少之又少。“美”这个概念在专业讨论中几乎不见踪影；最多，人们会提及Stripe的文档，或称赞Viam文档站点看起来不错，但却说不出究竟是什么让它们显得优美。当然，存在许多与之相关的讨论和观点，比如在人机交互领域。
例如，在一篇被广泛引用的论文（Tractinsky等人所著，《美的即好用的》）中，作者发现感知美学与感知可用性之间存在很强的相关性，而且这种相关性在人们实际使用系统后变得 更强 了。在讨论部分，他们引用了克里斯蒂娜·胡珀的《建筑设计：一种类比》，该文出自唐纳德·A·诺曼和斯蒂芬·W·德雷珀于1986年编辑的经典著作《以用户为中心的系统设计》。
“信息系统的设计……常常被比作建筑设计。……胡珀写道，建筑分析之所以强调建筑的立面，有几个原因。其中原因之一是，立面是建筑的引介：‘这是大多数人直接体验到的’。此外，立面可以作为‘内部与外部的膜，其目的在于阐明两者之间的关系。’”
在技术写作领域，丹尼尔·普罗西达将“质量”视为文档的关键属性，区分了功能质量和深层质量，后者包括 使用起来感觉良好 和 具有美感 。普罗西达认为深层质量以功能质量为先决条件；换句话说，你不可能先拥有漂亮的文档，除非文档本身是能用的。我也在我提出的“文档需求层次”理论中捍卫过这一观点。后来，埃利斯·普拉特让我想到了维特鲁威，他提出了建筑的三大支柱：坚固、实用和美观。而美观，正是我们一直忽视的那一个。
在我们的技艺中，功能总是凌驾于形式之上。Write the Docs社区的一位作者曾告诉我：“如果文档试图变得漂亮，那它们就在背离自己的目的。”然而，随着时间的推移，我开始怀疑，我们称之为文档之美或良好用户体验的东西确实存在且很重要，而且它与图形设计和视觉效果关系不大，更多地与文档的产生、编辑和组织方式有关。就像书架上整齐排列的一行书会产生一种愉悦感一样，结构清晰、呈现得当的文档也能带来同样的感受。
此时，我祖国的一位作家——伊塔洛·卡尔维诺，进入了我们的视野。
重拾伊塔洛·卡尔维诺的《新千年文学备忘录》
1985年，就在去世前不久，伊塔洛·卡尔维诺撰写了一系列关于文学未来的演讲稿，即《新千年文学备忘录》。每一篇演讲或备忘录都聚焦于一种不同的文学品质。虽然很难确认同样涉猎过科幻小说的卡尔维诺在写这些讲稿时是否想到了技术，但我确信，他并没有忽视这样一个事实：21世纪的人们会以不同的方式阅读，部分原因也正是技术。这就是为什么我认为他的思想可以很好地迁移到技术写作领域，对此卡尔维诺或许会带着好奇，甚至是反讽的态度来看待。
卡尔维诺计划在哈佛大学发表的这六个文学品质是： 轻逸、迅捷、确切、可视性、繁复，以及一贯性 。这些词与我心目中理想的文档品质产生了如此强烈的共鸣，以至于我忍不住想要在他每一课的教诲与技术写作的可能含义之间搭建桥梁，同时避免生搬硬套到文档及其要求上。我想卡尔维诺本人不会介意。
轻逸：能化解难题、扫除障碍的文档
卡尔维诺的第一课是关于 轻逸 的，我们不敢用这个词来形容文档，更不用说文学了。卡尔维诺非常清楚人们对他这一选择的可能反应，并精心阐述了他所理解的“轻逸”的含义。在这个过程中，他对比了云的轻灵与硬件的沉重，并评论道：
“软件若非凭借硬件之沉重，便无法发挥其轻灵之力，然而发号施令的是软件，它作用于外部世界和那些仅作为其软件功能而存在的机器上，这些机器不断演化，以便运行日益复杂的程序。”
就文档而言，我们可以说，轻逸是指有能力解释最沉重的技术概念和操作流程，而不给读者带来负担。轻逸意味着通过避免晦涩和停滞来实现清晰。当文档传递知识的许诺，却不附加其沉重感时，它就是优美的。那些能“微笑面对”（化解难题）的文档，在保持准确的同时，也做到了轻逸。
迅捷：不浪费你时间的文档
优美的文档能快速切入主题。它们无需旁征博引、东拉西扯，因为它们出自一位既精通主题又了解受众的作者之手。他们能寻得最有效的捷径，直达预期的反馈或洞见。这种讲述故事的迅捷感，部分得益于重复（比如“每一页都是首页”的理念，对吧？）。卡尔维诺说：
“民间传统中口头讲故事的手艺，是由功能性的考量塑造的；它省略无关紧要的细节，并坚持重复……孩子们听故事的乐趣之一，就在于期待某种重复：情境、表达方式、惯用短语。”
文档在讲述“如何做”的简短故事时，应当是程式化的、一致的。技术写作、诗歌和代码的共同点在于简洁。能用一句话说清的事情，就绝不用迂回冗长的解释来增加读者的脑力负担，这样的文档让我们的大脑更愉悦。文档的迅捷，在于它不浪费时间。
确切：拒绝模糊的文档
这个品质对技术作家来说应该不足为奇。我们由衷地喜爱精准、确切的文档。我们 看重 的是确切的 数值 的存在。当我们为某个含义找到了最贴切的词语时，一阵愉悦感会沿脊柱而下。文档的“道德律令”就是将语言作为工具，以最小的阻力传递知识。
“对我来说，确切首先意味着三件事：
1. 为作品设计一个明确、周详的计划； 2. 唤起清晰、锐利、令人难忘的意象； 3. 在词语选择和表达思想与想象的细微差别时，语言尽可能精确。” “在我看来，语言总是被以一种松散、随意、粗心的方式使用，这让我感到难以忍受的恼火。”
即便拥有世界上最精确的词语，也无法拯救一个放错了位置、归错了标题、处于错误结构中的页面。文档的确切性，首先在于知道每个页面的用途，然后才是如何书写它。当文档的每一个层级，从站点地图到提示标注，都拒绝模糊时，它就是确切的（也是优美的）。
可视性：帮助我们在脑海中重建知识的文档
当卡尔维诺写到 可视性 时，他评论了文学的一种品质，即让读者能在脑海中“看见”事物，实际上是去 想象 事物。或许是担忧多媒体噪音的逼近，他捍卫了文学中词语的唤起力量（并由此推及所有形式的书面交流）：
“我将可视性纳入值得保存的品质之列，是因为我们正面临失去一种基本的人类能力的危险：即闭上眼睛也能让幻象变得清晰的能力，让色彩和形状从白色页面上的一排排黑色字符中涌现出来的能力，通过图像进行思考的能力。”
当概念性文档能让读者“看见”架构，或者当教程能让读者“看见”自己双手在键盘上操作时，文档就是优美的。图表和截图能起到辅助作用，但它们常常是为了弥补那些未能独自在读者心中形成画面的文字。当读者可以闭上眼睛，却依然能看见页面所描述的内容时，文档便具备了可视性。
繁复：蕴含多重维度的文档
卡尔维诺认为“每一个生命都是一部百科全书”，并将那些雄心勃勃的文学作品描述为能够同时容纳多种知识的工艺品，将不同的声音和语域编织进一个统一的整体，却又不将它们混为一谈。这种抱负同样适用于文档，文档本质上就是多元的，包含不同的内容类型。
“当科学开始不信任那些不够精准或不够专业化的普遍解释和解决方案时，文学面临的巨大挑战将是学会将不同种类的知识和不同的代码编织成一个对世界的多元的、多面的愿景。”
当文档胸怀远大抱负时，它们就是优美的。它们通过从多个角度覆盖用户关注的全部范围来实现这一点，就像我在“七行动文档模型”中介绍的那样。一位技术写作同行凯文·库尔将其比作一个优美的数学证明，它不仅因为正确而优美，更因为它连接了所有的部分。优美的文档容纳着不同的声音，它们共享着同一个书架。
一贯性：如预期般流畅的文档
卡尔维诺在完成他的第六课之前就去世了。我们只能猜测他本会就此说些什么，但我们知道，如果说有一个品质是所有技术作家都会赋予优美文档的，那就是一贯性。当文档的展开可预测，并且在我们期望的位置为我们提供有价值的信息时，我们会感到愉悦。
你可以在风格指南、代码检查工具和术语表中找到一贯性。你也可以在一致的UI行为中找到它。但让文档变得优美的那种一贯性，是一种感觉，即每个页面都出自同一个头脑，作者清楚产品是什么，读者想要做什么。当读者感觉不到其中的接缝时，文档就是一贯的。
六个词，摆脱文档的“粗野主义”
我将卡尔维诺的备忘录带到这里，是作为一个“引子”（spunto），一个意大利语词汇，意指引发更大事物的小东西。我们应该就“什么成就了文档之美”展开一场对话。我们的技艺在功能上高度聚焦了太久，以至于相关讨论已变得“粗野主义”（注：此处指风格单一、功能至上、缺乏情感）。我们争论工具和逗号，却不去问是什么让用户愿意回到文档。
技术写作也是一种文学体裁。一种体裁可以很美，而不必假装自己是小说。参考页面能以诗歌无法企及的方式做到“确切”。教程能以散文无法做到的方式做到“轻逸”。卡尔维诺给了我们六个起点词汇；也许你心目中的词汇有所不同。剩下的路该由我们来书写，但首先，我们必须开始 在意它 。