埏埴以为器,当其无,有器之用。
粘土做成陶器,中间必须留空,才能作为器皿使用。
-
可伸缩性和互操作性比不必要的功能更为重要。规模来自于简单,快速和轻松。互操作性来自朴实和易于消化内容。
-
让人减少分心,可提高写作质量和阅读效率。
-
新功能永远不应该干扰最简单的用例,并且应该对不需要它们的用户保持不可见。
-
本指南是为普通水平的工程师设计的——只想早点回去写代码的忙碌的工程师。庞大而复杂的文档是可能的但不是主要重点。
-
最小化上下文切换使人更快乐。工程师应该能够使用与读取和编写代码相同的工具与文档进行交互。
-
纯文本不仅够用,而且效果更好。Markdown 本身不是这个目标必不可少的,但它是当前最好且得到最广泛支持的解决方案。通常不鼓励使用 HTML。
-
内容和展示不应混杂。应该始终能做到不需要渲染器从源文件中就能读取到基本信息。不应该强迫用户不得不去接触展示层。
-
可移植性和面向未来为将来意料不到的整合留下了空间,最好通过使源文件尽可能地易于人读来实现。
-
静态内容比动态内容要好,因为内容不应取决于任何一台服务器的功能。但是,“新鲜胜过陈旧”。我们努力平衡这些需求。
-
当文档被像测试一样认真维护时,就会蓬勃发展:这是一种需要学会品味的必要的琐事,因为它会随着时间带来回报。请参阅最佳实践。
-
简短和功利胜于冗长而详细。绝大多数用户仅需要作者全部知识的一小部分,但他们需要经常快速。
-
渐进式改善比长期争论要好。耐心和对不完美的宽容允许项目有机地发展。
-
不要舔饼干译注1,而要递盘子。我们沉浸在具有潜在影响力的项目中。只选择那些你能真正处理得了的事情,放过那些处理不了的。
译注1:舔饼干。儿童故事中,小孩暂时不想吃饼干但是又怕被别人吃掉,就舔了放回盘子里的行为。 在西方职场中用来比喻抢了活不干让别人也干不了的行为。这种行为影响组织整体效率。参见 Raymond Chen 的博文 Microspeak: Cookie licking。