人们通常把文档看作纯粹功能性的产物 —— 一包内容，能用就行，用过即忘。但真正读过文档的人都知道：一份手册、一个文档网站，能否抚慰心智、打动感官，是有明确差别的。那种一页就懂、一眼入心的感受，我们都曾体会。既然我们认同文档本身就是一款产品，那为什么不把它做得让使用者愉悦？如果文档是产品的入口，难道不该让人产生好感、愿意反复查阅、更加信任吗？好文档能赋予人力量，能留下真正的知识。好文档，是可以治愈人的。在大模型正批量生产既无审美也无判断力的 “流水线文档” 之际，追问 “什么让文档变美” 尤为重要。我写下这篇文章，正是为了开启这场讨论，也为给自己寻找灵感。在技术写作的话语里，“美” 几乎缺席
关于 “美” 与文档的讨论少得可怜。专业场合里几乎不见 “美感” 二字；人们最多会说 Stripe 文档不错、Viam 文档好看，却说不清到底美在何处。当然，人机交互等领域有不少旁涉的讨论。一篇被广泛引用的论文《美的即是可用的》（What is beautiful is usable）中，作者发现：审美感知与可用性感知高度相关，且在使用系统后这种关联会更强。文中引用了克里斯蒂娜・胡珀的观点：信息系统的设计常被比作建筑设计。建筑分析之所以重视立面，是因为立面是建筑的面孔，是大多数人最直接的体验；它也是内外之间的一层膜，负责清晰表达内外的关系。
技术写作领域中，丹尼尔・普罗奇达将文档质量分为功能质量与深层质量—— 后者就包含好用、好看。他认为深层质量必须建立在功能质量之上：先有用，后有美。我在《文档需求金字塔》一文中也持同样观点。随后，埃利斯・普拉特提醒我想起维特鲁威提出的建筑三支柱：坚固、实用、美观。而第三点，正是我们一直忽略的。在我们这一行，功能永远压倒形式。一位写作社区的朋友说：“如果文档忙着变美，它就已经失职了。” 但我渐渐相信：文档的美、好的用户体验，真实存在且至关重要；它和视觉设计关系不大，更多关乎生产、编辑与组织的方式。就像书架上整齐排列的书会让人愉悦，结构清晰、呈现得体的文档同样如此。也正是在这里，意大利作家伊塔洛・卡尔维诺走进了视野。重回卡尔维诺：给未来千年的六篇备忘录
1985 年，去世前不久，卡尔维诺为文学的未来写下六篇讲稿：《新千年文学备忘录》。每一篇都聚焦一种文学品质。尽管无法确认这位曾涉足科幻的作家在写作时是否想到科技，但我确信他不会忽视 21 世纪人们因技术而改变的阅读方式。因此我相信，他的思想完全可以平移到技术写作 —— 他大概率会带着好奇，甚至一丝反讽，看待这件事。卡尔维诺原定在哈佛讲授的六种品质是：轻逸、迅速、精确、显见、繁复、一致。这些词与我心中好文档的气质如此契合，我忍不住把它们一一对应到文档写作上 —— 不生硬套用，只做真诚的连接。我想卡尔维诺不会介意。一、轻逸 Lightness
—— 笑着讲清复杂，卸下读者的负担
卡尔维诺的第一讲是轻逸。这个词我们几乎不敢用在文档上，更别说文学。他很清楚人们的反应，因此仔细界定了它的含义：软件唯有借助硬件的沉重，才能施展其轻逸的力量；但真正主导的是软件，它作用于世界与机器，而机器只因软件而存在，并为运行更复杂的程序不断进化。
放到文档里，轻逸就是：用最不费力的方式，讲清最沉重的技术与流程。轻逸是清晰，是拒绝晦涩与拖沓。文档之美，在于它给出知识的承诺，却不附加知识的重负。笑着讲清楚的文档，才是既轻盈又准确的文档。二、迅速 Quickness
—— 不浪费读者一秒钟
美的文档直奔主题。它不绕弯，因为写作者既懂主题，也懂读者。它能用最短路径抵达目标、给出洞见。这种迅速，一部分来自重复与范式 —— 比如 “每页都是首页” 的设计原则。民间口头讲故事的技艺，由功能性塑造：省略无意义细节，坚持必要重复…… 孩子听故事的乐趣之一，就是期待某些重复：场景、句式、固定表达。
文档应当范式化、一致化，用最短的故事讲清 “如何操作”。技术写作、诗歌、代码，共享同一种美德：简洁。能用一句话说清，就不用大段迂回占满读者心智。不浪费时间的文档，才叫迅速。三、精确 Exactitude
—— 拒绝模棱两可
对技术写作者而言，精确本就天经地义。我们痴迷准确、珍视确切数值、为一个恰到好处的词感到通体舒畅。文档的道德使命，就是用语言把知识以最低摩擦传递出去。清晰、审慎的整体设计；
唤起明确、锐利、难忘的意象；
用词精准，能表达思想与想象的细微层次。
我总觉得语言正被随意、松散、草率地使用，这让我难以忍受。
世界上最精准的词，也救不了放错位置、归错标题、嵌错结构的页面。文档的精确，始于知道这一页为何存在，再谈如何书写。从站点地图到提示框，每一层都拒绝含糊 —— 这样的文档，才精确、才美。四、显见 Visibility
—— 让读者在脑中重建知识
卡尔维诺谈 “显见”，是指文学能让读者在脑海中看见事物、形成想象。面对即将到来的多媒体喧嚣，他捍卫文字的唤起力 —— 并延伸到一切书面表达：我把显见列入值得守护的品质，因为我们正面临丧失一种基本人类能力的危险：闭着眼睛也能浮现景象，从白纸上的黑字里唤醒色彩与形状，用图像思考。
美的文档是这样的：架构文档能让读者看见架构；教程能让读者看见自己在键盘上操作。图表和截图有用，但往往只是在弥补文字无法造像的缺陷。读者闭上眼睛，仍能看见页面所描述的一切—— 这样的文档，才叫显见。五、繁复 Multiplicity
—— 容纳万千，而不坍缩为一
卡尔维诺认为 “每一段人生都是一部百科全书”。他推崇那些能同时承载多种知识、把不同声音与语调编织成整体、却不强行同一的文学作品。这种抱负，同样适用于天生多元的文档。当科学开始不信任笼统的解释与非专精的解决方案，文学的巨大挑战，便是学会把不同知识、不同符号编织在一起，形成一个多元、多面向的世界图景。
美的文档有格局。它从多个角度覆盖用户的全部关切，如同我在 “七行动文档模型” 中提出的那样。一位同行曾把它比作优美的数学证明：它之所以美，不是因为正确，而是因为把所有碎片连成一体。六、一致 Consistency
—— 如期而至，流畅无痕
卡尔维诺生前未能写完第六讲。我们只能猜测，但有一点确定无疑：在所有技术写作者心中，能让文档变美的品质，一定包括一致。我们偏爱 predictable 的流动：信息出现在它该出现的地方，手感稳定、节奏如常。一致体现在风格指南、校验工具、术语表，也体现在始终如一的界面行为。但让文档变美的那种一致，是一种整体感：每一页都像来自同一个心智，作者清楚产品是什么、读者要什么。六个词，逃离文档的 “粗野主义”
我把卡尔维诺的备忘录带到这里，是当作一个spunto—— 意大利词，意为 “一点引子，开启更大的事”。我们应当认真讨论：到底什么让文档变美。我们的手艺太久聚焦于功能，话语已经变得粗野。我们争论工具、纠结逗号，却不问：是什么让用户愿意回到文档面前？技术写作也是一种文学。一种文体不必假装成小说，也可以很美。参考页可以拥有诗歌无法企及的精确。教程可以拥有散文无法企及的轻逸。卡尔维诺给了我们六个词作为开端。你的词或许不同。剩下的篇章，由我们来写。但首先，我们必须开始在乎。https://passo.uno/what-makes-docs-beautiful/
夜雨聆风
